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Lasso Studio and Lasso Web 
Data Engine. Lead The Way 


Building custom and shrink-wrapped database-driven Web applications requires a whole new way 
of doing things. Having pioneered the Web Data Engine^" over three years ago, Blue World and 
the Lasso Web Data Engine consistently lead the way providing a feature set Web developers 
describe as incredible." Build online stores, discussion forums, resource management systems and 
other demanding database-driven Web applications with unrivaled performance, ease, security, 
extensibility, control and flexibility. Develop using multiple languages^—including LDML, CDML, 
Server-Side JavaScript, Java and XML— and deploy across multiple platforms* Your Lasso code 
works identically regardless to which database you're connected. Lasso solutions for FileMaker® Pro 
databases easily scale to big iron ODBC-compliant databases like Oracle, Informix, Sybase and 
more with little or no change. What's more, the Lasso Java Application Programming Interface 
(LJAPI) provides developers an easy-to-use Java-based API for unprecedented extensibility. 

Find out why hundreds of thousands of websites rely on award-winning Lasso technology for their 
business critical Web data* Download a 30-day evaluation copy at www, blue wo rid* com/d own load/ 
or order securely online today at the Blue World Store at store.bluewofld*com* 


Lasso Product Lin# - The leading Web tools for Macintosh and beyond. 


bring business to the internets 
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Without a doubif the Premiere Resource Editor 
for the Mac OS p.. A wealth of time-saving tools.” 

- MacUser Magazine Eddy Awards 

"A distinct improvement over Apple's ResEdii.'' 

— MacTech Magazine 

‘'Every Mac OS developer should own a copy ofResorceren 

- Leonard Rosenihal, Aladdin Systems 

''Without Resorcerer^ our localization efforts would look like a ^ 

T}}wer of BabeL Don't do product without itr 

— Greg GalanoSj CEO and President, Metrowerks 

‘'Resorcerer's data template system is amazing/' 

- Bill Goodman, author of Smaller Installer and Compact Pro 

^‘Resorcerer Rocks! Buy it, you will NOT regret it. ” 

- Joe Zobkiw, author of A Frfigment of Your Imcigination 

“Resorcerer will pay for itself many times over in saved time and effort.^ 

- MacUser review 

“The template that disassembles 'PlCT's is awesomer A 

— Bill Steinberg, author of Pyro! and PBTools 

‘‘Resorcerer proved indispensible in its own creationP 
— Doug McKenna, author of Resoreerer 




Version 2.0 



• Very fast, HFS browser for viewing file tree of all volumes 

• Extensibility for new Ilesorcerer Apprentices (CFM plug-ins) 

• New AppleScript Dictionaiy (*aete*) Apprentice Editor 

• MacOS 8 Appearance Manager-savvy Control Editor 

• PowerFlant text traits and menu command support 

• Complete AfFF sound file disassembly template 

• Big*, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 



liequires System 7.0 or greater, 
1,5MB RAM, CD-ROM 


Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it’s easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-filc-based, design and operation 
Ail flic information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rez-like scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, ‘ietb’s, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Maci ntosh developers around the world 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PC's, or Visa/MC 
Taxes: Colorado customers only 


Extras (call, fax, or email us): 
COD, FedEx, UPS Bluemed, 
International Shipping 


MATHEMAISTHETICS, INC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
r esorcerer&nathcm a esth e tics. com 


Tb order by credit card, or to get the latest news, bug fixes, updates, and apprcntic!es, visit our website^.. 


www.mathemaesthetics*com 
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VIEWPOINT 


By Nick DeMeilo 


This Muy, Apple is hosting it's Worldwide Developers 
Conference in San Jose California. Promoting development 
solutions For Macintosh is essential to Apple's survival. Apple 
makes their money liy selling Macinto.sh, but people only buy 
Macintosh to make use of those solutions. Apple isn't in the 
business of creating ao<i selling word processing [programs, 
i’lrowsers, compilers, gaine.s, tools like Photoshop, Premiere, 
Eudora, FileMaker, Excel and the next great and unknown 
product that some is building in his basement right now. But 
Apple wouldn't lx: able to sell very many Macs if those 
solutions didn't exist and weren't continuing to Ix' developed 
for Macintosh. WWDC is the one week a year when Apple 
calls together as many developers as lliey can and makes 
ihetr pilch as lo wfiy people should develop for Macintosh. 

Tlie convention will be broken into at least five tmeks of 
related presentations and workshops. The first of these tracks 
will Focus on the Mac OS. This core OS is one of the most 
important parts of Macintosh. This year the hxus will l)e on 
Mac OS X, Expect piesentations on just about every pan oF Mac 
OS X; the Darwin Core, Quartz imaging mode!, At|ua interface, 
Cocoa application Framework, and Carlxm coinplianc’C For 
migrating older applications. For years Apple has taken heal 
about the core of tlietr system lacking si!<‘h essential fealures a 
true multitasking ami protected ineniory, liiis year iheyH bnally 
l>e able to deliver those as well as some tally inntwative and 
fundamental new^ technologies that will provide some 
compelling re:i.sons for develofxrrs to target Macintosh. 

Track two is a digital media track that will include 
QuickTime, OpenGL, and (not sure why ihis one is in Digital 
Media) Java. Over the last couple of years, Apfile has 
extended tlieir definition of "developer” in the same way the 
entire indu.siry luis. At one point providing solutions on the 
Macintosh meant you were a programmer, Ixit today content 
creators and media developers are a growing portion f>f the 
folks bringing products tt> the Macintosh platform. DVD 
movies and Streaming Media Channels are almost as 
t'omptflling a reason lo buy Macintosh as traditional soFlware. 
Expect to see sessions Focused on preparing, manipulating, 
and delivering rich digital media with the.se technologies. Tlic 
message in this track i.s that Macintosh Is the definitive 
platlorm for digitial media content and application 
development and delivery. 

Apple is a hardware company. The hardware track 
promises to give us a developers {Xfspective on Apple's 
current hardware technologies (including AltiVec and AirPon), 
interface standards like FireWire and USB, and a knik Ixrliind 
the curtain at whafs in iFie works For the next year A[>plc will 


make arguments for why the hardware component of 
MacinUish gives it a substantial edge over other platforms now 
and in the next year. They will prrwide reasons to locate your 
cpii or graphics intensive afiplications on Macintosh, as well 
try and tmlline opportunities to develop third party accessories 
to expand and support Macintosh. The exploskm of USB 
devices and potential of FireWire I rased products for the 
Macintosh is pretty gotxl denionstralitm t>f the effectiveness of 
these arguments from last year. 

ITie Network and .Security track give.s .some insight into 
how Apple see.s llic Macintosh platform sup|x>rting a new 
generation of applications. Apple's Sherlix'k 2, QuickTime IV, 
iDLsk, and KidSafe are showcases of Uow ilie new Mac OS can 
allow desktop applications to work transjxireiuly witli internet 
resources. The powerful new security, multi-user, and 
encryption features of the Mac OS coupled with new kind,H of 
connectivity through the Sherlock interlace, Streaming 
C^)uk:kTime, AppleShare IF (and Client SDK), NxSL, AppleScript 
TCIVIF, and otliers mean Macintosh hosted applicatioas can 
offei some great functionality for e-comnierce, 
conimunications, and network based coiiijxiUng. While many 
of these tectinolt>gies are not new, develnpcT's haven’t brought 
many related applications to market yet, Apple's promotion of 
iTools and now a WWDC tmek dt^clicaled to Network and 
Security seems in indicate their intent jump start development 
in this area and .stand behind the technologies theyVe 
developed for it. Fersonally, I tliink these iechn(*logies are 
likely to aisuli in .some of the most exciting new products for 
Macintosh and am looking ft award tti ifiese sessions. 

Hut it\s the la.st track that really caught my eye: Tools. 
Apple ha.s apparently devoted an entire etmference track to 
developer resources where they will reveal "Apple’s tools 
strategy and the future of development itJols on Mac OS.” On 
one hand Apple doc.sn’i have a very good track record with 
regard to deveJoper resources, I have lo look at this 
antiouncemenl through skeptici.sm colored by Bedrock, a lack 
of any printed API doeiimeniation, and eliarging develapers 
,S19S a pop to talk to Apple. On the other hand, the last few 
years have seen A]>ple make some bold and effective moves 
with regard to product design, development schedules, 
market position, advertising, and distribution. Em hoping 
weVe going to see a well thought out and long term 
developer resources plan that is just as innovative and 
successful. Fm hoping Apple plan's to make building 
Madntosli applkalions as easy as they've made using 
Macintosh and that the fifth track will l>e the most compelling 
reason yet to develop for Macintosh. K1 
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The key to 
thinking different... 



Question: Is MacHASP USB* a 
software security key or a 
sales tool? 

Answer: It's both! 

MacHASP USB is the world’s first 
software protection key for the 
iMac. it gives you sophisticated 
license enforcement and compre¬ 
hensive protection against illegal 
use... in other words, real security. 

Then it gives you a big seliing 
advantage. 

With MacHASP USB, you can 
license multiple software modules 
and applications. You can instantly 
unlock or upgrade them in the 
field. Pius you can freely distribute 
demos. 

Bottom line: MacHASP USB locks 
out illegal users and unlocks your 


full sales potential - without 
getting in anyone's way. Call now 
to request a Developer’s Kit and 
our newly published guide to USB 
features and benefits. 

*Fot all USB-aquipped Macs running an OS 
with USB support. Fully compatible with the 
AOB version of MacHASR 

^cdEiaBd^ . 

Mact)S 

USA: 1-800-223-4277 
212-564-5678 
Int’l: 972-3-6362222 

www.aks.com/mt 

ALADDIPJ 

KNOWLEDGE SYSTEMS LTD 


Mac software protection provider, Micro Macro Technologies, becomes part 
of Aiaddin, giving its customers even better service from the number one name. 



GETTIMC 

STARTED 


By Dan Parks Sydow 


Speech and Voices 


Writing a Macintosh program that 
makes use of different voices 

Two months a^o, Ckriting Statiad intrcxlucetl the Topic of 
ackliiig computcr-gcncmicd s[)ccx:li U? a Mac pn>gniiiL In that 
anicle you learned how to verily that the user’s Mac is able to 
output speech and then use the Toolbox SpeakStiing() function to 
spccik the text one string. \its\ niontli’s (rdltn}* Siarted anitic 
carried on witli the tofik of sfxx.xh by <.lemonstrating how a 
program can create a speech cliarmel in ordei’ to speak more tlian 
a single siring. This iiionih we coniplcie the trilogy of spextch 
articles by seeing how a sfjeech channel is used by a program ilia I 
wants to alter the voice lliais used in the generation of speech. 

Speech Basics Review 

A Mac program that is to s]xnik should include the Speech.h 
iinivei-siil headei- file to make sure that the comj^iler recognizes the 
speech-related Toollx)x funttions, 'Hie prt)gram should also verily 
that the user’s Mac is able to geneitile sjx\;ch. After ifial, a string f)f 
text can he spf>ken by calling the 'rcK>llTox funaion SpeakStringO. A 
Pascal-formaaed string is the only argument. Alter that, repeatedly 
call the T(K)11 xix function SpeechBusyO to allow for the Mac to 
complete talking, if tlie following snippet dtx?srft look familiar, refer 
back to the January Started article lor more information, 

Ifinclude <Speech,k> 

OSErr err: 
long response: 
long mask: 

nrr =■ Gestalt [ geslaUSpeecbAttr, &r«sponi;e )i 
if ( err 1 “ aoErr ) 

DaEirrnr( “\pError railing Gestalt'' } : 

mask ^ t <C gestaltSpeechKErPreaent; 

If £ response h niask ™ 0 ] 

DoErrorC “\pSpeech Manager not present " ); 

err = SpsakStringt 'ApThis Is a test." ): 
if ( err [= tioErr ) 

DoError£ ''\pError attempting to speak a phrase" ): 
while f SpeechBusyO ^ true ) 

Speech Channels Re\tew 

Ust month’s Getting Started intrcxluced speech channels. In 
order to specify which voice to use, you’re program needs to 


allocate such a channel — so take a quick look at some of the 
exxie from last month. 

A sfieech cfrannel is a dala stmeture that holds descriptive 
information about the voice that is to be used to speak. If you’re 
program needs to alternate voices, you may want to create two 
or more speech channels — one for each voice. The Toolbox 
function NewSpeechChanneiO cTcates a new speech channel 
record and returns a SpeechChannel — a pointer to that record. 

SpeechChannei channel; 

OSEir err; 

err “ NewSpeechChanneK nil. ^channel ): 

The first NewSpeechChannel() argument is a pointer to a 
voice specification data strucuire. Passing a value of nil as the first 
argument results in as.signing the system default voice as the 
voice to tie used by speec h that cfxne.s eventually comes from 
iliis new channel. 

VCHCES 

To this ptjint we’ve relied on the default voice — the voice 
the user’s Mac uses wlien a f>rogram doesn’t specify a paiticular 
voice. As shown in Figure 1, the_user uses the Speech control 
panel lo determine which voice Ls lo be the default voice. 



As shown on the left (if Figure 2, the Speecli control 
panel includes a pop-up menu that lets die user choose a 
voice. And as shown on the right of Figure 2, each voice in 
the Speech control panel pop-up menu corresponds to a 
voice in the System Folder of the user’s Mac (in the Voices 
folder in the Extensions folder, to be exact). 
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SPI tracks down software pirates 
with every iiiegal ciick. 


SPI adds a protective layer to your program that allows only those end users who legitimate¬ 
ly purchase your software to install It. No matter how many copies of your program get 
distributed illegally, only the valid purchaser can install and run your product. 

For just pennies a copy, you can protect all your products and significantly 
increase your revenue without increasing production costs. 

Features: 

" Win95, Win98, Win2000, WinNT, Mae/PowerMac ’ Resource Encryption 

• Key File Encryption • 3 Built-in Demo Modes - Builtdn Online Registration 

• Built-in General Purpose Registers ‘ Distribute via CD/DVD, Diskette, Internet 


Sell your software without 
a shopping cart. 


With SPrs builHn e-Commerce feature, distribute and sell your software m one easy step. 

Your customers situ ply download your SPI protected product and select Purchase 
when they run the installer. After entering their credit card information, SPI uses 
identity authentication, packet encryption and a set^ure link between SPf and tire 
authonzing agent to protect the transaction. Upon authorization, your product is 
installed and ready to run. You can even set up a “try-before-you-huy” demo that 
can then be upgraded using SPl’s e-Commerce featicre when the demo expires. 

Features: 

* Real-Time Authorization thru CyherCash™ or Authorize.NoP'^ - No Web Store 
Front Required ' 3-tier IVansactitm Protection * Upgr^ade Demos to Full Version 
from Original Product Installer Download • Purchase/Tracking Reports Provide 
Additional Credit Card Charge-Rack Protection Reduces Web Hosting Charges 

No special hardware required. 


SPI doesnl require expensive hardware keys or dongles to prelect your software. Besides, 
you can't download a dongie. SPI uses an encrypted software lock to protect 
installed files. Once a legal product is installed, SPl’s Lock Point feature prevents 
illegal copies from running on any other computer, while SPPs uninstall feature 
allows end-users to move a protected product to another computer. Sirnply run 
the installer again and RPl disables the first installation, allowing the software 
to be installed on another computer. 


See for yourself how SPI 
protects ycur prcducts. 


Visit our web site at www.nwspi.com to request our SPf Evaluation Kit. The SPI 

Evaluation Kit will allow you to protect one of your softwai'e produces for 
up to one month. Each Evaluation Kit comes complete with the cross-pi at form 
SPI software, APIs and the SPI User's Guide outlining all of SPl's features. 
You can test every feature of SPI, including the built-in e-Commerce feature 
with a special merchant account set up just for testing purposes. Request 
your SPI Evaluation Kit today. 
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Figure 2 Each mna* in tbeS}mcb control panel pap-up merm 
corTc^}onds lo a ^^ystam mice file. 


As shown ill Figure 2, voices eaeli liave a name. So it mighi 
seem logical tliat yoLir program would ehtx>se a voice based on 
ils name. However, suc'h is nor ihe ease. Voice files am he added 
and removed from llie Voices foldeg and there's no way of 
ensuring that any one partiojlar voice is present in ihc Voices 
folder of every Mat* user. So nrtlier than specifying a voice by 
name, ytiur program should specify one or inore I'haracteristics 
the desired voice should have. After that your program can 
examine the voices pre.sent on the user’s machine in order to 
find an appropriate voice. When a march is found, the voice can 
be as.stxiated with a .speech channel, and sul>sec|ucni lexi that is 
sent lo that channel will !>e spoken using the desired voice. 

The diita that makes up any one voic'e can Ix^: placed in a 
VoiceDesciiption diia stmeture. Such a smKiua.^ has several fields, the 
mast imjxjttant of wiiich ate die gender and age delds. Well look at 
these fields after fli^st learning how a VoiceDescription is olxained. 


Obtaining tlie Description of a Voice 

lb find a voiexf iliat meets your needs, your f^ji^igram wiH 
examine the voices in the Voices folder of the irsefs machine. Begin 
thLs cluire i>y deleniiiiiing how nuiny voic es are in tiial folder. A call 
to die 'icx)![x>x function CountVoices() returus this nunilxT in ils one 
argLimeni. (Jse thc^ nuinlxa of voicus a.s a Irxip auinter, wliere the 
ixxly of die ]cx)f) examines eat:h voic:e for a suinible match. 

OSErr err; 

.'ilifjrt numVo \ ces; 
shor L i: 

err “ CountVoices( SnumVoices): 

for C i = i; 1 <= numVolcesi j+*r ) 

I 

// obtain a vtocc: iktstTiption for oiir yoicr 

\ 


Obtaining a voice takes two steps. The first step is to get a 
VoiceSpec for a voice. The VoiceSpec cx>nsists of an identification 
number of the sjxech syndiesi^er for which die voice was 
created, and an identification number for the voice ilselh Any 
number of voke.s can share the same speech synthesizer (1), but 
each voice of tliose voices with the same speech synthesizer ID 


will I lave a v<nce ID tfiat is unkjue. Passing the r(Kdlx>x function 
GetlndVoiceO an index of a voice in the Voices folder results in 
GetIndVoiceO returning a VoiceSpec for that one voice. We’ll he 
fplacing tlic call to GetlndVoice() within the above for loop, so we 
can use the current loop counter as die indexi 

VoiceSpec theVoiceSpec; 

err = GetlndVoicef 1, SlhcVolceSpec ); 

The VoiceSpec for a voice let's ii.se access the 
VoiceDescription structure of dial voice. Call the Tcxilhox function 
GetVoiceOescriptfonO to do that. 

VoiceDesc riptio n voiceDe s c: 

firr = GetVni fieri pt 1 on f t hcVoiceSpec, ^voiceDosc, 

( voiceDesc ) ) : 

The first aigumenl lo GetVoiceDescfiption() is the just- 
olitained VoiceSpec, Tlie second argument is the VoiceDescription 
starcture, and will be filled in by GetVoiceDesciiptionO. The third 
argument is the numlter of bytes in the returned VoiceDescription 
structure. Use the sizeot() funcli<iTi to get this value. Here’s how 
the voice-selecting axle looks — so far: 

OSErr errj 

short ntjmVoloefi: 

.■^hort I \ 

Vo t roSpec t heVo j ccSpec; 

VoiLeDt?Bt:riptioiivoiceDG sc: 

err = CountVoices C StnumVoices): 

for ( t = ]; i <= ooinVoIc.ES; t++ ) 

I 

err ^ GellndVolcet I. &theVoiceSpec )r 

err = GetVoiceDescriptionC tbeVoiceSpet. ivoiceEeac* 
sizeoft voiceDesc ) ): 

if examine tlie chanaeristies of this one voire 


Selecting a Voice Based On Characteristics 

At this f>oint we know how to determine the number of 
voices in the user’s Voices folder and then gel a VoiceDescription 
for each voice. Now we need to look at how we select a voice 
based on information in that VoiceDescription .siniaure. For most 
programmers tlie most meaningful fields ol' tlii.s structure are die 
gender field and the age field. 

The gender field can have one of' three values, each 
represenletl by an Af)|)k-defined cionsUinl. Tlie kMale and kFemale 
gender values are self-explanatory'. Tlie third gender value, kNeuter, 
describes a voice that is rolxJtic-sounding. 'Ihe age field holds the 
approximate age lhai a speaker of a voice would have. 

If you want your program to generaie sfxedi using a male 
voice, yoifll be testing the gender field of a VoiceDeschption 
structure. Assuming weVe used die above method to obtain a 
VoiceDescription for a voice, tliai test looks like this: 

if f voireDESn.gender kMale ) 

If you want your prognim to generate speech using a voice 
of a teenager, then you’d lest die age field of a VoiceDescription 
structure. Again assuming a VoiceDescription has already been 
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()[>iiiincd, llic axJc to the task at hand lfX)ks like this^ 

if t { volceHefif*a£R > 12 ) && f voiceDesc.ate C 20 ) ) 

// wi'^vc found a ttxnagr voii’e 

And il' we want to specify a voice based on both the ^jender 
and the age? C()ml>ine Ixnh tests (which order you peTforni llie 
tests in isn*t important). 

if ( t voiceDesc,age > \2 ) f»h i voicpDesc.age < 20 ) ] 

I 

If ( volceDesc.gender “ kHale ) 

// wc'w fijund IfK; volet of a itcnagc male 

I 


Using the Selected Voice 

When weVe Ibund VoiceDescription information that 
matches our voice interests, weVe found a suitable voit:e- If 
working from witliin a loop, now’s the time to leniiinate the 
loop and make use of the VoiceSpec. 

for t 1 “ 1: i riuraVolccs: i++ 3 
1 

err • CetlndVoiceC 1* itheVoiceSpec 

err = GecVoiceDeficrlptiont theVqiceSpec* ivolceUesc* 
sizeofI voiceDesc ) ): 

il C { voltoDeoc.age > 12 3 ( voiceDesc*age < 20 3 ) 

r 

if ( volceDesc .gender = ) 

// use the VoiceSfJCC held in variable tlicVoiccSptx’ 

I 


Last month you saw the creation of a new speech channel 
handled in this manner: 

Sp eec hChann el c ha tin e i; 

err - KewSpeechChannel( nil. ichaimel 3j 

Using nil as the llrsi argument meant the returned speech 
channel makes use of the default voice. If we now in.ste;icl pass 
the just-obtained VoiceSpec, the speech channel will lx.* created 
such that it makes use of die voice referenced by this VoiceSpec: 

err ^ NevSpC!f3chChunrioH SllieVolceSpet:, &channql ); 

last month*H (k*Uin^ Starit^i article inmxluced SpeakTextO, the 
T<x>l[)ox function that six^iiks text from a buffer, 'the first aigument 
to that routine is a SpeechChannel. Now tliat the channel variable 
references a speech channel that's as.s(K:iaied with a sfxcific voice, 
tiiai voice (rather dian the systan default voice) will lx used in the 
generation of the speech that SpeakText{} emits, 

ftrr ^ SpeekTextf channel, (Ftr)(str + 1}* strlOj 3: 


SpfechVoice 

This month's program is SpeechVoke. Wlien you run 
Speech Voice you'll lie presented w'ith the dialog box pictured 
in Figure 3^ 
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Figure 3, The SpeechVoice diahg hiix. 


In tlie Speech^feice diiilcjg lxx\ ycxi dick ( jn one of two mciio 
buLU^ns uj .seleti a voice to use, then click die Play Speech liution lo 
have the pnograin sjxrak die string '7^ this the txHce yotTre iooking 
Jbrf** using the seledecl voiccv If die user’s mac^hine doesn't hokl a 
voice that has the specified charaaeiistics, the program instead uses 
die system default voic:e. Ycxi can repeat the process of dicxxsing a 
voice and speiiking die plirase as often as you wish. When finished, 
click the Quit bunon to end die prograiic 


CREATiNt; niE SpkechVoice Resoltrces 
Start your resource development liy creating a new folder 
named SpeechVoice in your ni;iin CodeWarrior folder. Start 
ResEdii and create a new resource file tiiimed SpeechVoice.rsre. 
Specify that the SpeechVoice folder aci as the resource file's 
destination, lliis resource file requires four resoutK:es, two of 
which youVe very familiar with: die one ALRT and one of die two 
DHLs. ALRT 128 and the ccjmesponding DITL 128 togetlier define 
the program's error-handling alert. If (he SpeechVoice prognim 
doesn’t exjiedence a serious error while executing, then this alert 
won't lx; seen by the user. 

Ilie remaining tw'o resources are DLOG 129 and its 
cxirresponding DITL 129. Togedier diese lestiuires define the diiilog 
Ixix shown back in Figure 3. 'iTie size. placemenL and tyjx^ of 
dialog dial die DLOG defines aren’t too criUcai. thougli it nvakes 
sense to selea die rype dmt dcxsnT have a close box (since the 
dialog ts to remain on-screen until die user quits), Figua* 4 show's 
die Dm dial defines (he type and phe^ment of the items in die 
dialog box. To view die item numbers {as displayed in Figure 4), 
check Show Item Numbers from ResEdifs DHL menu. Take note of 
die item numbers — they’ll appear as coasianis in the soutxx* txxJc. 
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Figure 4 The SpeechVoice resources. 


Creatlng the SpiOiaiVoiCE Project 
Create a new^ projett liy launching QxleWurrior and choosing 
New Project from die Rle memu. Use the MacOS:C_C^H':MacOS 
TooftxMcMacOS Toofiwx Multi-Target pni^xX .stationary for the new 
pnijtxt. Uncheck the Create Folder check box, dien click die OK 
bunon. Name die jinojcxn SpeechVoice.mcp and choose die existing 
SpeechVoice folder as the project's deslinalkin. 

A<id the SpeechVorce rsrc resource file to tlie project, 
then remove the SillyBalls rsrc file. You can remove the ANSI 
Libraries folder if you want as the pnijeci won't be making 
use of liny ANSI C libraries. 

If you jilan on making a PowerF<2 version or fiit version of die 
SpeechVoice pnogniin, add die SpeechLib library to die two 
PowerPC laigets of your project. As iix-ndtined in last month's 
Geliing Slar^^d, ycxi’ll wim to clioose Add Hies frtini die Project 
meny and dien maneuver your way to this library. Ihe most likely 
spot TO find this library is in die Metrowerks CodeWarrioriMacOS 
SupporttUbrariesiMacOSCkimmon folder. If it's not diere, use ShcTltxk 
to seardi your IxirI drive. After adding the iibmry to the project, 
QxleWanior dls^ibys a dialog [x>x asking you which targets to add 
ihe liiimry to. Check the two PK.' targets. 

Now^ t:reate a new^ source code window by choosing New 
from the Hie menu.. When you .save the window, give it the 
name SpeechVolce.c. CIi<k)sc Add Window from die Project menu 
to ad<l the new empty file to the project. Now remove ilie 
SillyBalls.c placeholder file from the project window. You're all 
set to type in tlie source ctxle. 

If you want to save yourself a liule lyiiing, connect u> 
the Iniernei and visit MacTech's ftp site at 
flp://ftp.mactGch.com/src/. There youTI find the SpeechVoice 
source code file available for dow'nloading. 

Waixinc; Through the Source Code 
SpeechVoice.c Ix'gias wiili die in<Tii.sion of die Speech.h file: 

llncludf' <Speech.h> 


After the #include comes a numlx-r of aiastimts, most of which 
are rostxircc-relaied. Tlie amsiani kALRTReslD holds the ID of the 
ALRT resoLirc'e used to define die em>r-liandling alerl. kDLOGResID 
holds the ID of die DLOG resource used lu define die prognini’s 
dialog box. The constants h PI ay Speech Button, 

kSetSpeechWomanRadio, kSetSpeechRobolRadio, and kQuitButton 
each hold the item nunilxr of one iif the items in tlie dialog Ixix 
(cx)m[Tare tliese constants lo the items in DITL 129 as shown back in 
Figure 4), Tlie consiani kNoMatchingVoiceErr is our own (arbitrary) 
value dial wee'll use in the event the jiiograiu fail.s in iLs attempt to 
find an appropriate voia*. TTic constants kCkintrolOn and kControlOff 
are used in the turning on and off of the dialog tx)x nidio buttons. 




V 

^define 

kALRTResID 

128 


kDLOCResID 

129 

^define 

kPlaySpeechButton 

1 

^define 

kSetSpeBqhVfonianRsd io 

2 

define 

kSetSpeechRobotRfldio 

3 

i'define 

kQuitButton 

h 

#define 

kNoMa i c It i ogVo i c eE r r 

-999 
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#flt?r.lrvo kContfolOr 1 

jfdefine kCotitrolOff 0 


Next come the program's function prototypes, 
tunctions 

void ToolRoxTnit( void ); 

void OporiSi>t;ochnialoB,( void ); 

SpetchChantiiil Op<?iietit^Sp(?t;clsCharmc] t VolceSpec )[ 

OSErr GetVoiceSpecBasedOnAgeCendet: ( VoiceSpec * + 

short* short H slioti 

): 

void DoErcor( Str255 errorString ): 


Tile main() runciion of S[xjcch\bke I:>egins witii tJie declaration 
oi' dime variables, all of which aie used in the determination of 
whether speech generation is possible <m the user's Mac. 

ii^jii ******* *** ******^ 

void maint void ) 

I 

OSErr err; 
lung rospDJiGO: 
long 

After the T(m>IIx)x is initialized tlie speech-related LesLs (as 
dc’scnl)c‘d in [anutiry's G/tlifjg Siarteci) arc made. Alter dial nuiin 
ends with a call to the application-defined function 
OpenSpeechDialogO. 

ToolBox1nit t); 

err = Gestalt[ gestaltSpeechAttr; ifresponse ): 
if { err != noErr ) 

DoErrort '‘\pRrror calling Gestalt" ): 


Str255 str this the voice youVre looking for?" 

short agelow; 

short agcJligh; 

short gRnder: 

VoiceSpec defaultVoiceSpec: 

VoiceSpec theVoiceSpec: 

VolceDescriptionvoiceDesc: 


Creating a new^ dialog box, and saving a pointer to it in 
variable dialog, is die first order of business: 

dialog ^ GatNewDialogC kDLOGResiD. nil. tWindowPtr) IL ); 

liolh radio buttons will iniiially appear unselected, so it's 
up to us to turn one on. GetDiafoglt 0 m() returns (among other 
pieces of information) a handle to the item named in the 
second argumenl. This generic handle is then typecast to a 
ConfrolHandle and used in a call to SetControlValue() to turn 
the radio button on. To let the routine know which radio 
button is now on, tiic variable old Radio is set to match die 
item number of the just turned on button. 

GetDlelogItem{ dialog, kSetSpeechWomanEadio, &type, 

^handla, ^rsjct ); 

SetCofiitrolVal 11^=1 ( { ControlHaudle )haodle, kControlOn ): 

oldRadio ’ kSetSpoGchWomanRadio; 

Now we'l! call ShowWindow() to handle the case of a DLOG 
resource that SfK^cified that the dialog box Ije initially visible. A 
call to SetPortO ensures that the newly opened dialog box i.s the 
window that receives ypebtting. 

ShowWiodow( dialog ); 

SetPort( dialog ); 


mask = 1 « gos t ai tS POOL hfl^r Pres on L: 
if { response & mask = 0 ) 

DoError{ “\pSpeech Manager not present ): 

OpenSpeechDialogO I 


ToolBoxInitO remains the same as previous versions. 

^*****************Too[Bf:>x.inii 

void TpqlBoxInitC void } 

I 

InitGraf( Sqd.thePort ); 

InitFonts(); 

TnjtWindowfji): 

IjiiLMcnw.‘s[) T 
TKinitO ; 

tniCDialogst nil ); 

InitCurfiOrO ; 

! 


OpenSpeechDialogO Is responsible for opening, 
displaying, and monitoring the program's dialog box. If s also 
responsible for generating speech. The function begins with 
a host of variable declarations, each to be discussed at the 
time ifs used in the function: 


DialogPtr 
short 
short 
H^ndle 
kec I 
short 
Boolean 
OSErr 

Sp&GGhChannel 


dialog: 
oldJLadio: 
type: 
handle; 
rent: 
item; 

done = false: 
err: 

channel; 


Before jumping into Uiu loop that will watch for, and 
handle, liie user’s actions, we need to take one more preliminary 
step. As shown earlier in this article, the GetVoiceDescriptionO 
function is usually called with a VoiceSpec as ifie first aigument. 
If a value of nil is passed instead, then a VoiceOescription for die 
system default voice is returned. We’U do that here in order to 
get, and save, the default voice. If our later attempts to find a 
particular vtace fail, we'll use die system voice. 

err = Get VolceDcscr I ption ( nil, SivnicfiDesc . 

si7.eof( vnlce.Desf! ) ) ; 

defeuItVoiceEpec = voiceDesc.voice: 

We now begin die while loop that exeaites until the user 
clicks the dialog box Quit burton. When the user clicks on any 
one of die four items in die dialog box, Modal Dial og() returns the 
item number of die clicked-on item. We use tliat returned value 
in a switch statement: 

while ( done ^ false ) 

[ 

ModalDiaiogC nil* &item ): 

switch ( item ) 


!f the user clicks on the radio bulLon laticied Woman: 20 - 40 
years, tlicn the following code executes: 

case kSetSpcfichWomanRartio: 

GclDialoglLem{ dialog, k^SetSpeechWomanRadio* S:typG, 
ifbandlts, &rect ); 
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SetContrci 1Value( (ControiBandle1 handle, kControTOn 

): 

GetDialo^TreinC dialog* oldRadio, ilype, ^handle. 
&rec t ): 

SeIControlValue( {GoatroUlEmdle)handle. kControiOff); 

oldRadio ^ kSetSpeechWoinanRadio: 

gender = kFemale: 

agaLow = 20: 

ageHigh = 40: 

break: 


[n ihh new version we pass a VoiceSpec along for use in 
opening tlie channel. This is the VoiceSpec returned [>y 
Ge1VoiceSpecBasedOnAgeGend6r(} (or the VoiceSpec of die 
default voice in the event that a matching voice wasn’t found). 

clrannel = OpenOiieSpeechChannei ( theVoiceSpec J: 
if ( channel = nil ) 

DoErrorC "\pErroi: opening a apeech channel" ): 


Tlie above code turns the previously off button on, then 
turns the previously on button off (got ilial?). The newly turned 
on button is now considered the old button — which’s 
information necejisary for the next time a radio button Ls clicked. 
Three local variables, gender, ageLow, and ageHigh, are then set 
to values appropriate to tlie selected option. Well use these 
values when the user eventually clicks the Play Speech button. 

If the user insleiKl clicks on the radio button labeled Robot: 
any age, then the following code execuios. Recall diat tlie Apple- 
defined coastant kNeuter Is used to specify a robotic voice. Since 
weVe set up this option such that there's no age restiictions on 
the voice, we set tfie lowc'st acceplahie age to 0 and the highest 
acceptable age to an arbitrarily large value (keeping in mind that 
a variable of type short can hold a value a little larger than 32,tXX)). 

case kSetSpeechRobotRadio: 

CetDiaioglterat dialog. kSetSpeecMobotRadio, ^itype. 
^handle. ^rect ): 

SetControlValueC (Controiaandlfijhandle. kCoiitrolOn ): 
GetDialogTtein{ dialog, oldRadlo, 6ityp«* 

^rircjct ) : 

S^lCui]LrolValue( [Controlllaridic)bandle. kCcmtroiOff): 

oldRadio = kSetSpeechRobotRadio; 

gender ^ kNeuter: 

ageLow “ 0: 

ageHigb = 30000: 

break; 


Clicking either of the radio huuons doesn’t cause a seaah for 
tile tlesired voice to Uike place. Instead, we wait until the user clicks 
the Play Speech button. When the user takes that .ste[>, wc c'^all uur 
applit-aiion-dennetI function GetVoiceSpecBaseciOnAgeGenc(er(). 
Wlien we pass ihLs function tlie adtlress of a VoiceSpec, a nmge of 
ages, and a gender, the llinaion searches tlie system for a vt)ice 
with matching chamcteristics and fills in the VoiceSpec variable with 
the voice s[x:ciriLaLion for that voice (more on this fundion ahead): 


cafle kPlt^ySpeeclibiit.ton: 

err = GeiVoicsSpecBasedOnAgsGender[ StheVoiteSpec, 

ageLow, ageHigh. gender 


GetVoiceSpecBasedOnAgeGenderO is written such iliat a failed 
aUempi to fincf a voice results in the returning of an ernir value of 
-999, or kNoMatchingVoiceEir. In .siic!lr a situation we set niir kx-'al 
theVoiceSpec variable to the jircviously saved default voic:e. For 
any other error value we instead call our own error-handling 
routine that displays a short mess^ige :md terminates the program. 

If t err ^ kHoHatchlugVoiceErr ) 
theVoiceSpec = defauItVoiceSpec; 
eiae if ( ett noEtr ) 

DoErrorC "\pError finding voite" ): 

Now it’s time to open a new speech channel. In last monilFs 
Getting Started we wrote OpertOneSpeechChannel() to handle 
Lliat task. Here we call a slightly modified version of diat routine. 


With a new speech channel ojxjn (and with that channel 
a,ssociateci with the desired voice), it’s time to test things out by 
speaking a phra.se. Variable str holds the text to speak. The 
SpeskTextO routine speaks the text of that string (refer to last 
month's Getting Started for the details on SpeakText{)). 

err = SpeakText( channel. (Ptr)(fitr + 1)* str[0] ); 
if ( err != noErr ) 

DQErtQr( '^\pError attempting to speak a phrase" ): 
while E Speechftufjy{) ^ true ) 


err = OisposeSpeechChannei[ channel ); 
if t err 1= noErr ) 

DoError( “VpError diaposing speech channel'* }; 
b teak: 


When the user is finished a click of the Quit button ends the 
dialog box lfx>p, and ends ihe program. 

case kGuiLButton; 
done = true: 
break; 

I 

f 

nisposeDIa 1 og{ dialog ): 


OpenSpeechDialogO made calls to two application- 
defined rt>uiines: GetVoiceSpecBasedOnAgeGenderO 
OpenOneSpeechChannelO, Here's that first routine: 

OSErr GetVoiceSpecBasedOnAgeGender( 

VqlceSpec'theVoiceSpec* 
short ngeLow, 

^hort stgeliigh. 

short gender ) 

I 

OSErr err: 

short nuniVoices; 

short 1: 

VoiceDe script! envoi ceDeflf;; 

err ComiLVoiceE( i&iiuniVoiceK )- 
if E err != noErr ) 
return ( err ): 

for ( 1 ^ 1: 1 nutnVoices: li^ ) 

I 

err ” GctTndVoice( [* theVolccSpee ); 

If E on 1“ rioErt J 
return ( err }: 

err GetVqiceDescrlptlonE theVoiceSpec* fiivoiceDesc. 

siaeofE voiceDesc ) ): 
if ( err != noErr ) 
return E err ) ; 




If E (voiceDesc .age >= ageLov) 

(voiceDesc,age ageHigh) 

if ( voiceDesc.gender ^ gender ) 
return f noErr ): 


return ( kHoMatchingVoiceErr ): 

I 
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We on get by with very little de^iCTiplive in(^>rmation about 
this it)utine beaiuse its ccxle has already been descriix^d in this 
article, Kec'^ill that CountVoices{) retiiras the niimlier of voices in the 
user's system^ and that number ty'An then be ust?d as a loop index. 
Each pass through tlic kxjj:> calls GetlndVoice() to ol>taiii a voice 
speciftotion for one voice, and tiien calls GetVoiceDescription() to 
get the voice description of that one voice. b\om Ihe voitr 
descrijXion it can be deteriniiicd if a suiuible inatdi liiLS lx;en 
made. Here we look to see if tlie voice^s age falls into tlie range of 
ageLow and ageHigh, and whether the voice is of the proper 
gender. 11' a rnatch is made, return ends llte lcx)p. At this point 
theVoiceSpec holds die voice sjx^cificaiion for a matching voice. 

'I'he second application-defined function called by 
OpenSpeechDialogO Ls OpenOneSpeechChannelO. As you saw^ in 
la,si monllfs article, litis routine calls NewSpeechChannelO to create 
a new speech channel. List month we pas,seci nil as the first 
ai)7umenL, telling NewSpeechChannel() to a.sscx:iate the system 
default voice witlt die clianncl Here we pass in a vtnee 
.specification and use that as the fir.st argument, telling 
NewSpeechChannelO to as.s(x:iate this voice with the new channel 

r .. OixuOncSfKrcfhCh^nud 

SpeechChanneJ OpenOneSpeechChannei( VoiceSpec theVoiceSpec ) 

SpeechChannfll channel: 

OSKrr err: 

err = NewSp^^echChannel( ^theVolceSpec, Scchanriel ): 
if t err f= noErr ] 

I 

err DisposeSpeechChannel{ channel ): 
channel = nil: 

] 

rcLtirn ( channel ): 

] 


DoError{) Is unchange<! from prior version.s. A call to this 
function results in the posting of an alert that holds an error 
messiige. After the alert is dismissed the program ends. 

void DoErrort Str2.‘>^ nrrorSt,rin& ) 

I 

ParamToxtt errorStriog, "Vp't "\p'\ ‘tp"" 1; 

StopAlert^ kALRTReslE, nil ); 

ExitToShellO: 

I 

Running SpeechVoice 

Run SpeechVoice by choo.sing Run from CodeWirrior's 
Project menu. After the code is compiled, Code Warrior 
launche.s the SpeechVoice program. After you’re satisfied that 
the program does in fact select and u.se an appropriate voice, 
click the Quit button to c|uiL 

Till Next Month.,. 

Twt> months ago you saw how a Mac program can speak 
the text in a single string. Last month you feamed how your 
program can use a buffer and a speech channel to speak larger 
a mourns of text. And finally, rhis month you read up on how to 
select a voice and then tise ihaE voice in generating speech. You 
can learn still more about speech and voices by reading the 
Sound volume of Imide Macintosk You can also learn more 
alK)uL voices l)y experimenting witli die SpeeeliVoice code. For 
starters, try adding a diird radit^ bum>n that specifies different 
voice chamcteristics. By the time you have speech fully 
integrated inLt> your own program, you 11 he ready to read up on 
a new topic in next month’s Geliing Siarted Ki 
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TOOLS OF 
THE TRADE 


By Bill von Hagen 


Put Your Network Under a 
Microscope With EtherPeek 


Better living through 
network analysis software 


Networking is arguably the most 
important innovation in modern 
computing. Networks are the Irackboncs 
of most corporate and academic 
computing environments, plus access to 
the Internet is the most common reason 
for home conipuier purchases today. 
Unfortunately, diagnosing and resolving 
network problems poses a special set of 
headaches for system and network 
administrators. Bad network interface 
cards (NlCs), bad connections, had hubs, 
gateways, routers, or simply bad software 
can cause network prolilem.s. 

It wasn't that long ago that the first 
line of defense for network problems was 
an aniiada of scopes, line testers, and 
other medieval devices to help track down 
the source of a problem. IF the source of 
the pr()l)lcrn was a conif>uLer sysictn, 
system administrators could l>egin 
verifying the system’s hardware, 
configuration, network software, and then 
make coffee and exchange hex dumps of 
network packets all night long. 'I’he next 
advance in network problem analysis was 
dedicated [XJrtable hardware that you 
could attach to your network at any 
suspected trouble spot. Often laptops 
running .specialized software for capturing 
and analyzing network traffic were used. 
This is still a practical, sometimes 


necessary, option for organizations with extremely specialized 
needs (and unlimited budgets). 

A mcjre practical {)ption is to buy EtherPeek, put if on a 
dedicated Mac, and dare problems to occur on your network 
segment, EtherPeek is a great example of just how much 
software cm do to provide a c’omprehensive, understandable 
view of exactly what is happening on a network or network 
segment. EtherPeek makes it easy to identify and track down 
network problems before they bring your network to its knees. 
EtherPeek can also help you improve network performance by 
identifying hotspots or uimecessary network communication, It 
can identify abnormal traffic patterns and performance 
bottlenecks, and help you limit specific types of traffic to 
certain subncLs by selecting systems Uj group on tfieir own LAN 
segments. EtherPeek can also help you identify and eliminate 
unnecessary network ccjmmvinication, such as systems 
broadcasting or exporting network prtitocols that you don’t use, 
increasing the bandwidth for the network communication that 
you actually want to take place on your netwcjik. 

EtherPeek should only be installed on secure systems c)r 
servers to which access is restricted. It obtains the 
information it uses to analyze your network through what is 
called ‘‘packet sniffing.” It grabs a copy of every network 
information unit (packet) on your network as it goes past, 
regardless of the system or network address iheyfe intended 
for. (Ethernet tnrerfaces normally only accept packets that are 
intended For their hardware address.) Packet sniffing is the 
most conunon way for hackers (or whatever term you prefer) 
to obtain logins, passwords, and other supposedly secure 
informaiicm by eavesdropping on network eoinriiunication. 
General Network Diagnostics 

EtherPeek provides a number of floating diagnostic 
windows that enable you to monitor the general performance 
and status of a network wliile you use lis integrated capture 
and analysis commands to examine selected portions of those 
communications. When you first start RiherPeek, it displays a 


Bill vofi Hagen is a writer, computer system administrator, and the author of ‘‘SGML For Dummies/ You can contact 
him at wvh^gethip.com. 
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dialog in which you select tlic network imcrlace tlmt you 
want to monitor, After you select the appropriate netw^ork 
interface, you should also use the Capture menu's Network 
Speed command to verify that fieri^eek has detected the 
correct speed of your network (10 MB, 100 MB, or a custom 
OTHKR setting). Correct tltis setting if necessary. 

Etherheek then display.s a Network Statistics window that 
provides summary information about the amouni of traffic on 
your network. It uses a speedoineter/tachometer display to 
show network urdization and traffic at the current moment. 

Once yoLdre sure that you have EtlierPcek listening on the 
correct netwoik interface, the fun begins. Fiisi, obtain a 
summary of the network protocols tiiat are in use on your 
network. Select the Statistics menu's Protocols command that 
displays a Protocol Analysis window. ProU>col Analysis 
provides a constantly updated summary of the protocols in 
use on your network, grouping families of protocols together 
under their parent proioetds. Tlie ProltK:o! Statistics window 
samples the packets on the selected network interface at a 
configurable rate ranging from every second to every ten 
minutes, and displays a running histogram of the percentage 
of different [>rotQCols and packet types seen on your network. 

Figure T shows the Protocol Statistics window on a 
simple network where all of the currens traffic consists of 
TCP/IP protocols such as, .secure HTTP, and TELNET. This is 
the sort of display that you would see on a network 


composetl primarily of UNIX systems, where none of the 
standard Apple or Microsoft protocols arc i)eing used. 



Figure L The Protocol Slaii^itics WindotiK 

To watch a specific family of prtHocoIs, dick on the 
arrowhead beside other family names to hide the protocols in 
tho.se families, which helps you focus on those that you are 
specifically inierested. Figure 2 show^s a Protocol Smtistics 
window after bringing up a PC with AppleTalk support on 
the same network, with all of the Ethernet Type 2 protocols 
collapsed. Thi.s shows Apple’s AppleTalk protocol, the 
standard PC networking proiocols (IPX, IPX-LSAP, 
NetBElf I/Net Bios), and the Datagrams associated with PC 
Server Message Block (SMB) file and device sharing. 
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Can't find anyone to help you get your product to market ? 
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Figure Z Protocol Smtistics Window With Additional ProUKoh. 


All of EtherPeek^s statistics windows can be sorted by any 
field, just click on ihc heading for that field; this is a very nice 
feature. For example, you could click the Bytes header in the 
Protocol Statistic-s window to son its contents by the number of 
bytes being sent wiihin each prot<K:t>l family. Tfiis makes it easy 
to sec tlie heaviest uscxl protocols on your netwcjirk. 

Protocol statistics can be quite useful to identify the 
types of traffic going out over your network and the amount 
of traffic using each protocol, t)ut don't provide detailed 
information about the sy.stems between which that traffic is 
taking place. 'I'he Statistics menu's Nodes command display.s 
that information. Each host that is communicating on your 
network is identified by its MAC address, which is the unique 
hardware addre.s.s of an Ethernet card. 1o make this 
information useful* each MAC addres.s i.s followed by each 
protocol family address that communicates using that 
hardware address, Tigure 3 shows a .sample Node Statistics 
window in which you can see that the MAC address 
00:00:94:85:72:A5 is receiving IP packets as the address 
192.168.6.85, wtiile the MAC address 00:00:CO:8C:CE:92 is 
handling both the AppleTalk address Al -65339.7 and the IP 
address 192.168.6.95. 



The Node St^itistics window makes it easy to verify 
which hosts are communicating on your network, which 
protocols theyTe using, and the amount of traffic to and frmn 
each node. 'Ibis can be very useful in identifying whether 
heavy network users are using the recommended protocols. 
For example* many UNIX sites Lise software or special 
hardware that enables them to use AppleTalk over IP to 


spool print jobs from j^rint servers to Apple LaserWriters on 
their networks. Any Macintosh on the same network can 
print directly to a l^aserWriter by simply selecting ii from the 
Chooser, which would disrupt or suspend tlic UNIX [)rinL 
spooling and would not be logged by the UNIX spooling 
software. On primarily UNIX networks* you could easily spot 
this sort of disruption l)y watching for any IkjsLs that are not 
print servers Iiui which are sending lots of AppleTalk traffic. 

Identifying certain types of traffic can be useful, but ihe 
ability to identify the systems between which that traffic is 
flowing is usually more impoitanl in identifying performance 
problems. Select the Statistics menu's Conversation command 
to display a Conversation Statistics window that provides a 
summary of all communications between different network 
addresses. As shown in Figure 4* the Conversation Statistics 
window displays the source and de.stination nodes for each 
network conversation, tlie riumlicr of packets exchanged by 
those nodes, and the total number oi bytes in those 
conversations. T he Conversation Statistics window is updated 
every 5 seainds, by default, but you can change tlie update 
rate to any value between 5 seconds and one hour. 



Figure 4. The CorwersatUm Skiiistic^ Window, 


CAPTlfRlNG AND ANALYZING PACKETS 

EtherPeek's various statistics window's give you a great 
liigh-level picture of your network, but Lliagnosing actual 
network problems requires more informatitm than summaries 
and reports can provide. EtherPeek enables you to capture a 
SI ream of packets and examine them in detail, so it is easy 
for you to actually see problems . 

To capture packets, Select the I’ile menu's New option to 
display ihe Capture Buffer Opiions dialog. The Capture 
Buffer Options dialog lets you define various options for the 
buffer in which EtherPeek temporarily stores any captured 
packets . Next click the Continuous Capture f>plion and click 
OK. Once a pac kei capture window tlisplays, you click the 
Start Capture button to actually .start capturing packets. 
Figure 5 shows a sample capture window containing traffic 
betw'een hosts on a local network and actual Internet hosts. 
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Figure 5- A I^ckei CaiMure WmdouK 


Whenever possible, the packet capture window 
automatically uses DNS to resolve TP addresses into actual host 
nanies. Figure 5 sliows IkhIi addresses and host names 
ix'cause some of the systems on the test network use private li^ 
addresses that can't he resolved ihrougli a global DNS server. 

At any lime during or after t:oinpieting a pac ket taplure 
session, you can examine the contents of a ca[>tLrrcd packet in 
more detaiL Just double-click the packet you want to examine. 
This disfdays a wimkw that provides dtiailed information aNjut 
that packet, as shown in Figure 6. 
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Figure <x Captured Packel Details. 


Tlie detail window show^s the contents of the stJecml packet, 
iLs header, and the actual conienLs of iljc pat kei in licxacktiinal. Yon 
am click on any of the details shown in tlie tof) portion of a yyacket 
detail window to hlghJight tlie assoctitcxil raw jyicket cLtue 


Once youVe capiui’cxi ilic infomiarion you neeci, click the Stop 
Captute buttoti to teniiinate the f>ackct capture ,se,ssion. At this 
I^int, you can begin dehtigging or save the contents of the capture 
window for hirure analysis using the Pile menu's Save command. 

Using Packet Filters 

Capturing a constant stream of packets is a great diagnostic 
if youVe examining general networking issues, bill may often 
[Kovicle more inlbniiation that you need. To limit ca[>ttired 
packets, I'therPeek lets you create filters that ident% the paekets 
Llial you actually want to sec. FlherPeek supports two clas.ses of 
packet filters — simple filters let you capture pac kets ha,sed on 
S]Tecihc parts of their heacier, and advanced filter.s let you create 
complex Boolean expre.ssions based on header information or 
I>acket conlcnh Figure 7 sliow's HiherIVck's simple 11 Iter 
definition w indow. 



hthei Peck's simple filters let you restrict the captured 
packets hicsed on I heir source addres.s, protocol family, or the 
]Kat to which they are addressed. Port Ultcring is a great feature 
w^hen trying to dehtig netwx^rk problems related to a service 
such as m^, Telnet, or SendmaiJ that use.s a specific poit. 

EherPeck’s advanced filters lot you define niters using 
lioolean conibinatitms of the source address, protocol family, 
Lirget port, packet value, packet contents, packet length, or 
differem irackel errors. I^aekei conieni filtei's are esfxxaally useful 
wiien watching for network attacks. You can limit rlie cigxured 
packets to th(.xse that contain specitic string valuers, such as the 
password packeis used by the ITT .IN FT and l^fP pnaocols. 

AirrOMATiNG Your Network Debugging 

Althotigh FtherPeek's filters make It easy to capitire 
selected types of traffic in separate capture window.s, 
constantly scanning a large numljer of open capture 
wTn<k)w,s can Ix" confusing. A better approach to look for 
sfKxific events is lo have FdierPeck automatically perform 
some action wTienever the event occurs, such as beginning 


Makcii20(X) • MacTech 


Ptn' Your Network Under a MicRoscopr Wmi RrurKPiavK 


17 




























































































a jiackel capture sessioti or logging a iiie.ssage, EtherPeek 
provides three general ways of programming to 
automatirally react to specific network events: Triggers, 
plug-ins, and noiincalions. 

Triggers let you start or stop capturing packets at 
specific: Limes or when specific: network events occug 
based (in user defined filLers. Time triggers make it easy 
for you to automatically snapshot network traffic 
asscjciated with regularly scheduled ev^ents such as 
network l)ac:kups or aulcjmatic system reboots. Tliese are 
especially handy when you need to capture traffic 
snapshots for tasks scheduled at off-peak times, such as 4 
AM, when you miglil prefer to l>e home sleeping. Filter 
triggers fx^gin or end a packet capture session whenever 
the conditions defined in a specific filter are met. 

Plugdns are EtherPeek's most powerful meilKsd of 
reacting to specific events. Plug-ins arc external modules 
that perform detailed packet analysis and constantly 
monitor all seen packets . EtherPeek comes with a 
numtxTof [>lug-ins that perform tasks such as, looking for 
duplicate IP addresses, watching for specific types of 
network attacks, ancl unaly/Jng KIP, NetWare, and SMTP 
(email) traffic:. C>nc:e enalded, plug-ins are globally active; 
that means the traffic being captured by a filter trigger can 
he simultaneously analyzed by any number of plug-ins. 

Ik)th triggers and plug-ins have assoc iated severity 
levels, which make ii easy to integrate them with 
PaherPeek’s notifications. Notifications are actions that 
you associate with specific events in F.iherPeek, and 
consist i}\ any of five differeiii actions. You can log 
messages t(> EtliLTPeek’s log file, be paged (if you’re 
using supported paging server software, which is 
currently PagcNOWl), be sent email, use the Speech 
.Manager to announce tlie event, ov launch an AppleScript 
that you create to do anything you want. Notilications 
also have assot iaied seventy levels: informational, minor, 
major, and severe. Jilakes It is easy to create nolifieations 
with yt:>ur own names, select the action you want to 
assocfaiecl with them, and :issociaie them with a .specific* 
sevLTily level in EiherPeek s Notilications dialog . After 
notifications have been defined, any trigger or plug-in 
wath a .specific security level automatically triggers any 
notifications associated with that severity level, by 
default. EtherPeek comes with one predefined notification 
associated with all four severity levels - logging me.ssages 
to its log file. 

Generating Reports 

System and network administrators rarely have the 
luxury of sitting at a desk to just monitor EiherPcek 
statistics windows. Today's networked computing 
environments require office to office or wiring closet to 
wiring closet travel, .software and luirdware installation 
and , or sim[7ly debugging user problems. To help kee]7 
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an eye on your network while yoiPre off fire-fighting, or 
to get a high-level view of network performance for use 
at an upcoming meeting, you can set EtherPeek to 
automatically generate statistical repoits in HTML format. 

'Hie Statistics menu’s 1 friMl. C‘)urpiit command lets you 
configure tlie frequency with wliich tliesSe reports arc 
generated, the directory where the output files are placed, 
ancl a directory of report generation templates. EtherPeek 
generate.^ Protocol Stalistics and Node Slat is tics reports, 
plus a suoimary report that provides general inlbrmation 
about all of the tialfic on your netwe^rk. The Protocol ancl 
Node.s .Statistics reports exactly maLc:h the current view in 
the windows on your screen. For example, if you've 
collapsed or sotted families within the Protocol Statistics 
window^^ the repoit.s generated by EtherPeek arc collap.sed 
or sorted in the same way. 

Doctimentation 

EtherPeek is a rarity among modern software [xickagcs 
because it comes with a well wrinen, primed manual, You 
should think twace before buying a diagnostic tool that 
only comes wdth PDF manuals or other online 
documentation. Online doeumenLs can lx tricky to access 
when you're ex]>ei iencing haixfw^are problems. EtherPeek’s 
documenraiion not only explains the liitttons and how to 
use the dialogs, l>ul also includes multiple examples cjf 
how lo use EtherPeek \o monitor your network and 
lr<7ubleshoot various types oi problems, If you are new to 
network troulileshocTling, need some suggestions or just 
want a sanity check of your own approaches to 
troubleshooting, this informatiem is invaiiiable. 

Diagnosing tiie DiACiNOSTics 

Diagnostic tcjols are a tough business because they 
have to provide useful information when things are going 
well, handle a noma ions evenis w'iEli ease, and provide 
information al>out those anomalies in a useful form. 1'he 
last thing you need wlien experiencing a network problem 
is to iiave probk'ms with your (.liagnostic software. Luckily, 
when testing [vllieiPeek, I got a first-hand opportunity to 
submit a problem report and watch AG Group's customer 
support staff in action. 

One of the systems on my le.sl network dual-boots 
Windows 9H and the lieOS. The BeOS is somewhat picky 
about Kthernel card support, so I have two network cards 
in the macliine, one for each operating system with the 
other disabled by that operating sy.stcm. When the 
machine comes iip, the hub to wdiich these (*ards is 
connected erupt.s in a flood of blinking lights, indicating 
diaiLcT between the two cards until the OS de put .shuts 
dow n one of them. A perfect test! I started EtherPeek on 
a Mac, opened a packer capture window, and then fired 
up the dual-boot system and let the chattering begin. 
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With in scamds, ihc ProLocol Slat is lies wintJovv haci 
reported over 4000 different detected protocols , a big 
change from ihe 30 or so seen in normal circumstances- 
Each of the liogus protocols had a name of the form 
CTIIER-XX-XX, where X was a hex digit. Capiuririg all of 
these packets also brought the Mac to its knees. ’I'he only 
way 1 CO LI Id successfully slop the capture and save the 
contents of the capture buffer was to turn on continuous 
togging to disk and shut down the BeOS/Win9B box a 
second or two after ruining it on, l.ooking at the capture 
buffer, 1 ccjukl see that one of the cards was sending 
thousands of undersized and otherwise liogus packets, 

AG GrcHip’s customer support was quick to tell me that 
litc ErrHER’XX-XX packcLs meant that the value in iht^ type 
held Ibr those [jackets was not a kncjwn j^roiocol type. They 
also explained how to set up an Advanced l iker to ignore 
Lindefincd packet types, and even offered me a copy of an 
inciemental release of EtlterPeek with some new features to 
improve performance in heavy traffic situations, such as mine. 
(Coining socjn to the next version of EtherPeek!) Aclmittedly, 

I identified myself as someone wiio was reviewing their 
.software and thus your mileage may vary. The speed with 
which they responded and the quality' of their response meant 
that the su[:)port person I contacted actually imderst(XKi l^ah 
their soflw'aie and netv\x>rking in general 

Diagnostic tools carTt fix hardware problems, but 
they can tell you when to puni a cheap netw'ork card. In 


a real business situation, my NIC could have caused real 
performance f>ioblems for oilier users. Final score: cheap 
NIC, 0, EtherPeek and AG Group's support staff 10. 

Conclusion 

Network pit>l>lems are hard to ideniify and often 
harder to track dowm to a specific host or network device* 
EtherPeek simplifies network troubleshooting by 
providing excellent packet capture and analysis 
capabilities within a powerful, welEdesigned graphical 
inLcrface. If you manage a network, Ether Peek provides 
the capabilities and features you need. If you are in ihe 
network driver or netwajrk software bu.siness, EtherPeek 
.sliould be a fundamental part of yf)ur arsenal of 
debugging and verification tools. Beyond simply 
diagnosing problems, EtherPeek is also an excellent tcjol 
for enhancing netw'ork performance by identifying local 
network traffic dial you can isolate, and by helping you 
eliminate wasted traffic or questionable hardware. 

EtherPeek can turn any Mac on your network Ink) a 
powerful nelw'ork debugging and monitoring station capable 
of extmeting atlniiration and sysadmin envy fn>rn even the 
most hardened 1.1NIX geek. If your cjigaiiization doesiri already 
have Mac's, EtherPeek might just l:>e the besi argument you 
could offer for buying one. If you don't have Mat:s and your 
management won’t let you buy a sufXTior machine, EtherPeek 
is also available for Windows systenis. IS1 


Mac programming is complex. 
The answer is easy. 


Tools Plus 

r K 1 I 


LIBRARIES -^FRAMEWORK 



Rapid Development 
in your language. 

Tools Plus Pro quickly 
turns your greal ideas 
into great applications 
using C/C++ & Pascal. 

Everything works as 
soon as you create it. 

It's easy to learn, 
really easy to use, and 
a breeze to maintain. 


“Tbok l^us lii|;lLLy utnLitux^ fiicoei uf pLdin Lut lutk juu iIimii 
viiuiiLl pmgriiniininj! aSOTwEiiw,If yotJ waA m OC++ or TtwJi Plua 

#ttl litip jriH pnslHw; lKtr«r Jshjirewiin^ rml uppficiiU Icms." 

fflapMirU 


'■AEI ilk Jjl. jt’n Hdtif irK■.l^a.^^hl)l rkfi c^sHwtkw fif wxjiK... If ycni aw In 

(kveldfHn^ ji|ii]j|]i:atijujis liuil buk^ "gudky" witLLcn ull mcr UtatiiL, 
iiiflili ?iLit i|. fpf yoa." JWacTech 


llw rcmnies ant laott TOnipiK;l imd Hum miylhing you mijslK write..- 
EvEiry ik Triulit Pfiti b uscruL... it htu^ttn wkh ■Dn.W 

Micwind 


Tools Pbd SuppobL 
* CeM/tsniy. Syrn*nh* and THINK PanABl 
■■C, C++and Paacal 


- Wbc os ft and 7 


Still only 

$249 

CAcaitettfc icensa. Jusi 599IE 



MaEHiiiriii 



Cm»iT s. rm^nriw /WwovalBbisatDoTOiotKKt^^ 

Phorw: (h Ifl} £1 frS62B Phmi {fiffllO 

FfU. (Vt»>M7.|Eli9 

Empt wrtwKig-iilirilfftpftwm 
FfM F:*alWi#0fl Kit 


































































































DATA 

ACQUISITION ON 
THE MACINTOSH 


Hy Tom Djafadiningral 


Control Freaks Alert! 


A clean interface to Beehive 
Technologies’ABB I/O 
using object-oriented Lingo 


IlVrRODUCJION 

The ADB l/CJ by Beehive 
'lechntjinnies is a device which you can 
conned Hi a Macinlosli lo comnuiniciue 
witli exlemal electronics. Simply put, the 
A1)15 I/O provides digital inpLits read 
swiicliesj, digital (>ui[)uis fio swatc h ihings 
on or off) and analc^g inputs wilJi S-hit 
resolution (icj read all kinds of sensors). 
Kor I lie .Maciniosh plaifomc if has tipcned 
up areas of applk:alion lo mainslreatn 
users that were previously the scjle 
tenitoiy of electronic liohhyists or users 
w'iih liigh end daia :ia|Uisiiion hardware. 
A lew of those amas are home automalion, 
roboiics, kio.sks, sc.ientiric experiments and 
product .simulation. 

Many a)>|>lirations can communicate 
with the ADB l./O. One particularly 
powerful combination is the ADti I/O and 
Macromedia Director. F.ven if you intend m 
control your ADB I/O thiough Applel-vents 
or C/C++, you may find it worthwhile to 
test your .sea up with Director. Dlredor is 
easy lo ['trogram, especially when it conies 
lo the grajihical user interfhee. 

The?re is of course? a clowmside lo 
Directors ease of use? the leiiiptalion of 
slc^ppy programming. Director does not 
recjuire ytni to declare kxa! variables or 


provide function prototypes. Add Directorcs cryptic error 
ines,sages and your program c an turn into a langleti mess which 
is difficult to debug. While this is cjf course undesirable for any 
i:»rogram, with a ]^rogr;uii that communicates wath external 
devices, for example motors, the const^quences of messy 
programming may tie more severe. 

This article aims to help you in battling messy Director code. 
By using Directors object-oriented features you will get to htitkl 
a friendly and clean interface to the ADH I/O. In addition, in this 
article consisieril naming for variables is used, which may be of 
help to you in writing your tmn scripts. 

Reqiured Hardware and Sdhwaril 
Required Ixardwarej 

• A Macinio.sh with an ADB poll or a Mac iniosh wiih a USB 
port ami a Griflln Technology iMale tISB lo ADB adapter. 

• A Beehive Technologies' ADB I/O. 

Rf^quired software: 

• ADIi 1 O XCMDs 1.0.1. Hiis file comes with the ADB I/O. Tt 
is also downloadable from the Beehive Technologies wefksite. 

• Maerc>media Director 5 or 6 (I )irect<a 7 is n<compatible \\n\h 
the ADB i/O XOMDs 1.01 file. A Direc tor 7 compatible Xtni 
Ibr the ADB 1./0 is currently in beta and downloadable from 
the Beehive 'rechnologies w^disiie). Though this article 
explains things for Direc tor 6, ilie differences wulii Director 5 
are minimal and the sample files which accompany this 
article are provided in !^)th Director S and 6 versions. 

What You Meed t{) KNim 

You need to be familiar with Macromedia Director and its 
.scripting language Lingo. You need not liavc worked with ohjeta- 
orienuxl l.ingo. What you need to know about object-oriented 


Tom spent a large part of his life trying to work out whidi letter groupings niininiize ajnfusion when spelling out liis name 
on llie phorRs Ncjw tlial he lias toiitKl lEial njai-adi-nin-gnil leads to .signilkaiilly lx?tter re.siifrs than Dja-ja-di-nln-gjat, he can 
fully ccRueniraie on his re.scarch on imeraciion dcssign ai Delft I diversity. Since lie does not own any cats, you won’t find any 
pitrtnies of t lieni on wwvv-.io.tiitlel ft.n l/re.sea re}i/vormliieorie/d)aindiningrat. htnil. 
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Linji^o will lx? explained. You should lx? iainiliar with die 
capaliililies of the ADB I/O, tliou^^h a summary of what you 
need to know is provided, 

(.ONITN'I'S 

We will start with an inlK>duetir>n to ohjecNmented kin^o. 
Wt' will then cover the ADB 1/O's hardware and soli ware details 
relevant to this article, II'yon are already coiiiforUible with tiiese 
suhjec'ts, you may wish it> skifj them. Once we have established 
this j^round, we sian with liuilding a Director lingo object which 
ion us a hiendly and clean interface to the ADB I/O, At the end 
of this article you will find a section on troubleshooting and a 
sect ion with suggest it )ns ft )r e n han t ements, 

OBJFCrr-ORlFNTED LlNGO 

Instead of starting with a theoreticaf discu.ssion of the 
atlvaniages of obfect-orienied lango, we will dive straight in 
and [nit together a simple object-oriented Director movie, 1 
think you will find tliat the virtues of object-rnienletl Lingo 
are much easier to undersiand once you have seen a 
etjnerete example. Our movie c'onsisis of three ,scripis: a 
parent script, a movie script and a frame script. First we will 
write I he scri[)ts, then we will test and discuss the resulting 
movie. Dtm*t worry kK> much if you don't ctrmi>letely 'get it' 
when we write the scripts. All will l)e explained. 


Tile parent script 

A l>irectt)r object is descrilxxl in a [lareni script. Create a 
new mtwie hrst, then cTtrate a [xirent script by cluxising Script 
frt>m the Witidtw menu (Figure 1). I’he script window opens. 
Name the scri]>t by typing testParentScript in the field at the lop 
of the scripting window ( Figure 2). To make sure that the script 
is a parent .script, click on the info button (Figure 3) and chcxxse 
parent from the type ]K>[>up menu (Figure 4). Click OK 
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figure /, 0})ert fhc scripi trinciow 





Introducing... ^ ' 

_ versior-i 

Funnel 

Web 


Funnel Web's innovative design and 
powerful feature set helps make sense 
of complex Web sites by identifying 
key trends and events 

Features 

• point and click interface 

• over 50 reports and graphs 

• up to 50 times faster than 
major competitors 

• platform independent 

• works with any web server 
on the planet 

Advanced Technology 

• Event Messaging 

• Remote Administration 

• Realtime Monitoring 


Intelligent Web Monitoring and Analysis 


Accuracy, speed, ease of use and powerful report-formatting 
capabilities, makes Funnel Web the perfect solution for 
monitoring e-commerce, Intranet and Internet sites. 

Backed by Active Concepts unrivalled 24 hour technical support. 


Download a tree demo version at 
bttp ://www. actlveconcepts.com 
or visit our website to find out more 
about the killer Funnel Web Spider... 
























Hgnt'e 4 Make thescnfji a {mreat sertpi, 

Now on to [he part^nt script iLscU'. li consists of three* parts; 
a hi rifling hancllei; message handlers and pnjf)enies. We will 
dtsaiss each pan in turn. 

1. The birthing handler 

Tills is where a i hiltl objeci is createcL It typicilly has die Ibrm: 

on new m 
return me 
end 

The birthing handler retums a pointer to a newly created 
child object. We will atki one line of ctxle to our new handler to 
put a nie.Hs;ige in the nic's.sage lx>x lelUng us that the binliing 
handler was indeed called* 

on new me 

- print some feedback In the message window 

put “tl^e birthing handler of testParentScript was called* 

-- return a palniet to the new child object 
return me 
end 


2. Message handler 

In a message handier you can specify a lx:tiaviour of an 
ol^jed* A message liandicr has the form; 

on me^sageHandler me 
end 

We will create an message handler olied heflo which beeps 
and puls a message in the message box. 

on hollo mo 

- beep once 
beep 

- print some feedback In the message window 
put ’'Hello World e* 

end 

J. Properties 

A property Ls a variable tliai ix^longs tc^ an object* It is 
declared at the top of an object's parent script, preceded by the 
Lingo keyword pn)periy, like this: 

property pProperty 

Within ilie parent script you can set or get a property by fust 
its ruime; 

set pProperty 1 

set IVariable = pProporty 

When we test the Director movie, you will see how- to gel at 
a (iroperry from outside of tlie parent script. Notice how, to 
maintain an overview, we start a property witli ilie letter p and a 
ItK'al variable witli tlie letter I. For a full description of our naming 
tonvention for variables and [Xirameters* ple;i.se refer to Table L 


Prefix 

Suffix Meaning 

Example 

i 

inpul pa ram e!er 

(Channel 

1 

Icc^ variable 

iResiil 

c 

child objeci 

cADBt 

P 

properly variable 

pUni! 


Us! lieA va liable 

pChannerrypegALien 


Table I: Vmiahk and immneier naming commuiom 


For now, we will create a single property called pProjK-riy and 
two mem[x.T functions. One to set the value of pProperty and 
one to get the value of pProperty. 

property pFroperty 

on set Property me, iValue 
set pProperty = iVnlue 
end 

on get Property me 
return pProperty 
end 
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'rhc movie script 

To create the movie ^seript, bring up liie .scri])! window ii 
necessary and click on tlu^ + buuon lo cicrale a new script. Name 
the sc ript movieScript by typing into the held at the top of the script 
window . Click on die into button. A dialog box appears. Make sua* 
iliat movie Ls selected in the type |XJpL)|Mncnu. Click OK. 

In our movie script w'e wall w'rite two handlers. I he lirst 
one, startMovie, is called when the movie snin.s, die second one* 
stopMovie, us called when the movie stops. 

on startMovie 
end 

on oLopMovt#^ 
eiid 

la this ex;miple we will add some txxle to llie startMovie 
handier only. First w^e print some fecxllrack tt) the message 
w indow to sliow that the startMovie handler svas called. We then 
create a global called oTestObjecth Finally, we assign to diis 
global a child object nf tlie lestParenuScrifa that we wrote 
previously by c’iilling die Innhing handler 

on aLflitHovli? 

— print fixtJt)uc:k ui ihc wimkm' 

put “stattHovle was called." 

— tTCJitc li ciTcstOhicctl 

obfl t oTentOb jeciri 

— tniikt (/rcsiObjcctl a chikl ohj« T of the parcntJicripi tewQ^ianUStritit 

— by calling lIil- hirihing handler 

SCI iilbaOhjcct 1 - nctt* "itsiPiutiKScripO 

f^nd 

The frame script 

We will now creaie a simple Trame sebpt tt) make our 
Director movie Uxip in frame L In die score window, doulile 
dick on the score channel of frame I anti add one line d code 
to the exitFrame handler. 

on exltFraiie 

go to the t raise 
end 

Testing our movie 

It is time to test our tntwie. If you get stuck at any point and 
think it is because you did not quite get the explanation alx)ve, 
you may wish to look at testOOMovie.dir. Run the movie and 
o)x^n the message lx>x. ryi"*^* 

put oTestObj^ett 

Hie message box should display 
- (offspring “testParentScript" 2 Brfia/2a> 

indicating that oTestObjectI is a child object ba.stal on our 
testParentScript. Don't worry if the alpha-numeric string that you 
get tliffers from ilic one shown alx)ve. As thLs is a niemtiry^ 
addrc'.ss it is in fact higlily unlikely that it would Ixr tdeniital. 


Nuw' iry^ the hollo message haodlLT. Tlie syntax for .sending 
a mes.siige to a child otqeci is <messageHandler> <chndObject>. 

hello oTestObjectl 

'I’he Mac should beep and the message box should display 
"Hallo World 1" 

Now^ sc‘nd the getProperty message to our child olijecC Since 
getProperty is -a funulion (a liandler which returns a value), you 
need to enclose ils jxiranieters in round hnickets. 

put gt'iFropprty (oTefltObject 1) 

The messtige box show's that pProperty kis tfie value void. No 
worries, pPropeiiy has not lx*en .set yet. How type: 

fietProperty oTestObjectl, 1 

Now try again: 

put gptProperty (oTestObjeett) 

And you will see that pFroperty has changed its value rroni 
void to 1. 

setProperty and getProperty aa* message handlers which w^e 
wrote ourselves. Anodier way to set and get propertie.s of a c hild 
object outside of its parent .script is: 

flftt the (property) of <cbildObjeet> = (vuluo) 

SOT IVfl ruble = the (property) of (chlldObjecL) 

Notice how' we need to add the Ungt) ihe' keyword, now 
dial w'e tty to access a pri)tK*rty outside of its parent .setipt. 

Let's tryi 

iset the pProperty of oTestObjectl - 2 
put the pProtK?rty of oTestOb|ectl 

The message box slxiws that pProperty of oTestObjecH now 
has the value 2. 

Flay around w idi accessing properties dirough the message 
liandters setProperty and getProperty as well as with accessing 
tlie properties direcily ihnnigh the ^ilie' keyword. You %vill find 
that you can mix Ik)l1i methods. 

WliaTs the point of object-oriented Lingo? 

Before w'e answer that c(uestion, iry creating a second 
child object: 

seL oTofliObject2 = new (script "testParentScript") 

The message lx>x resjxinds witli 

- “now band 1or of testParentScript was called" 

Try trniering 
put pTfistObjeci?. 

'Ibe message !x)x res[x>nds with 

- (offspring “teatParonrScript" 2 876a6ee> 
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Not ire* hi]W the Licklress of oTestObject2 d if fens from the 
addreSvS of oTeslObjecll. ‘the values of the prt>jGerties arc also 
individual to eudi child o!>jct:L Try 

JsetProperty oTestObject 1, 7 
EetPropprty aTest0bjecl2, 666 

Now type: 

put getPropecty (oTestObjectl) 

'Ihe messiige lx>x sliows lliiit ilie propert>' pproperty ts now 7, 

And try: 

put geli'ruperty (oTeat0bject2) 

This rime the message Ixox njs|K)nds tfiai the piopeity 
pPn>Ix*ny etjuaLs 666. 'Ikit Is pretty kewh IxXh child ohjc'cls have 
a prt>|x*ity called pProperty bin eac'h atn hold a dilteamt value. 

This example illustrates the three ciiaracteastics of objeci- 
oricnicd lingo that we use in this article. Tlie first is ihe ability 
Co creaCe multiple chtkl f>hjecLs based on the same parent 
script, which are all capaf>Ie of listening to certain message 
tirrougfi rhe message handlers defined in lire pareni script, llie 
second ciiaracLeristic is the ability to hide code — in our ease 
a simple pul .statcmcnl “ within the birthing handler of a 
parent script. This code is auUanatieally executed when a child 
object is created. The third characteristic is the afhlity to assign 
individual proixTiy vaiiie.s to child objects. While these 
characteristics may seem trivial, we can use them to great effect 
in improving the cleanliness of our code. By hkling set-up 
details in the binhing (landler, these details are prevented fnim 
littering your main progranc fltnntgh the use of profxrties. 
variables can he encapsulated witliin an object, 'ilii.s greatly 
reduces the need for global variables. Global variables are a 
major source of bugs in Director because each time you forget 
to declare a variable as a glolxil, Directtjr will assume you are 
creating a new, local variable. 

You have now^ seen en(High tjf objecl-tjnented Lingo to 
he able to understand tlic ADB IT) parent script that we %\ij| 
build later on. However, there is a lot more u> object-oriented 
Lingo than you have sec^n so far. To learn more, you can 
have a look at DirecloTs on-line help under parent script or 
have a lt>ok at Small (1999). 

If you are lamiliar with scime other object-t>rientcd language 
such a,s C++ or Java, you will pn>bably have worked out the 
relationship between Lingo and general o}iject-f>nented 
terminology by now. A pareni scTipt is a combination of a .source 
and a lioadcr file in which you define an objeii, a birthing 
handler is a coastmetor, a message handler b die equivalent of 
a memlier function, a projx'rty Is a cbla memlxT and a child 
object is an instance. 

Till' ADB I/O IlARDWARF 

Units 

You am have a maximum of four ADB I/O units daisy 
chained to your Mac. Lacli ADB I/O nc?eds to lx .set to its own 
imkpie ID mimlxr. 


Ports 

*l he ADB yo has tw o jxirts, called port A and port B. Each 
port has four channels, Ihe channels of ix)rt A and B differ in 
their capabililie.s. 

Port A 

Each of the four c hannels of port A can lx configured as 
either a digital input or a digital output. Analog input is not 
possible on port A. Each channel can have either a relay or an 
opio-isolator installed. 'Ihe ADB I/O comes with a*lays pre- 
iastalled on all channels of port A, making them suitable for 
digital outpuL If you wfsli to use any of these channels for digital 
input, you will need to Replace a channers ahty )>y an opto- 
isolator. Tlirough ilie u.se of relays or opt(^isolato^s, external 
electronics are electrically isolated from llie ADB I/O. 

Port B 

port B allows not only digital input and digital output, but 
al.so analog input and an analog reference voltage. However, 
you cannot freely mix all four channel types. Only the Following 
configurations are allowed. 

analog in, analog in, analog in, analog in 

analog in, analog in, analog in, reference 

analog in. analog in, digital in/t>uL, digital in/uut 

digital in/out, digital in/om, digital in/oui, digital in/out 

Eiicli channel of f>orl B is ef|uipped with a jum|xr. A jumixr 
can lx .set to pull up. pull down or o]xn. For digital input, the 
jumper needs to lx* set to either piilkip or pulklown. Note that 
to switch a channel fixim titgiial (c) analog, you not only need to 
dtange the configuration ol port B through software, but you 
also need to move tlie jumpers. 

TilK ADB I/O SOFTWARF 

To use the ADB I/O with Director 5 or 6, XCMDs are ased. 
These come in a fife allied AD BIO XCMDs 1.01, You need to 
in:ike sure that this file resides in the same folder as your 
Director movie. We am have a look at the funciionaliiy offered 
by the ADBIO XCMDs 1.01 file by cieuting a simple Director 
movie (If you get slut k during the creation of this movie you can 
lake a peek at testXCMDs,dir). Start a new movie, create a movie 
script and add startMovie and stopMovie handlers like tiiis: 

on sLiirtMovie 

openXLib “ADB I/O XCMDs l,0*r 
end 

on sropMovie 

cl()(!eXI,ib “ADB I/O XGKDs 1.0.1" 
end 

Add a frame script in the .score cliannel of frame I to loop 
the movie. Run the movie and t>pen the message Ik>x. Now ty|x 

showxrab 
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A slew of Xtras, XCMDs and Xl'CNs si low li[>. We arc (inly 
inlerested in the ones diat coneern the AJ)BJO: 

- “ADB r/0 XCHBs LD.i" 

- XCHD: Flash ld:0 

XC«D: Picture Id:4 

XCMD: Palette 1(1:5 

XCMh: ADBRelnlt 1(116701 

XOKD: CopyRes Id:1077 

- XCKD: CoTiflguroAUBIO Id: 1200 

Xi:KD: SetAOHlC Td:120^ 

- XFCH: GetADDiO Id:1201 


For now let's look at Conll^ureADliK), SclADBIO and 
GelADBlO. Here only a short dcstTiption of these calls is ^^iven, 
I'or a full destTiption please refer to the ADB I/O manual. 


ConfigureADBIO 

• ConfigureADBIO lias ibe .syntax: 

CorifigureAORTO Ofnir) *<port>* ■ 
<ChaiineHTypu>, <nhannftl2Type^>, ^ 
<Channe 1 JTy p e> * < Che n ne UTy pe> 


• What does it do? 

With ConfigureADBIO you specify wlial function the lour 
channels of a particular jKxt of a particular ADli I/O unil 
should fulfill. 


• I'arameters 

Tlie first pammeten Unit, is used to addiess a particular ADR 
I/O unit and can r4ingc from I to 4* Hie serxmrl parameter, 
port, is tused to address either port A or p<Jrr H of an ADB I/O. 
The remaining parameters specify wliat channel type you 
wish to as.sign to each clianncl of the port. Keep in mind lliai 
the capabilities of the ports difier, if you call ConfigureADBIO 
with unallowed channel typers it will rctiim an error message. 

• Renirn valuer 

ConfigureADBIO returns eitlier 0 (success) or an enxjr siring 
(lailujx^). 

SetADBIO 

• SetADBiO has the syntax: 

SriADRTO <Unit?. <Port), CChuiiKul)^ 

<fJiuiibcr) i pC'high* [‘loW'>J 

• What tloes it do? 

You can think <jf tliis call as three .separate t:alls. All three 
versions afiply to digital outputs only. Tfie first version sets a 
channel of a port of a unit to high or tow: 

SprADBIO <Cbaiinol>. <‘hlghd ' totf' > 

The second sets a channel of a port of a unit to high or low for 
a cenain duration, after which it returns to the opposite state: 

SetAUBIO <Unit>. <Purl>i <nhannel>, < *high" j' low'>. <TiKic> 
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'Ihc ihM s^lh a [K>rl of a unit in such a way iluu die values of its 
channels form the binary c-quivalcnt of a decimal nuniL>er. 

SE?tADttlO <Port>. <NiiiibL>r> 

• Parameters 

You already know' the meaning of tlie Unit and Rort franimeteis. 
Channel sjx.*cifics the niimlx^r of a chinnel and should llierefore 
lx* in the range 1-4. 'higlj' nx^ans relay activecl on jx>rt A and 
+5V t>n pciit B, low' means teiay non-active on port A and OV 
on port B. Titiie specifies a dunition fr^jm 0-25.5 s in 0,ls 
increments through a inlcgcr nmging from 0 to 255. Numlxr 
ranges from 0 (all channels iow') to 15 (all cliaiinels liiglV). 

• Return values 

SelADBIO returns either 0 (success) or an error string 
(failureX 

GclADBlO 

• GetADBIO has the syntax: 

GetAnBTO(<Urdt>. <port>l, 'Utimber'^]) 

• What does It do? 

You can think of this oil a.s two separate calls. 'Ihe first 
version: 

aetADBIO«UiTit>. <Pqrt>I 

retLims a channel record with the channel type and channel 
value for eacli clianncl of a port: 

< Cha nne11Type >,<Channe11Va1u e > 

< Channa1 2 Type >,<Cha n nc12 VaIue > 

<Chantiel3Type> .<CbfliineijVaiue> 

CChaniiel ATypt'>. <€hannel4Vaiue> 

The second version: 

GetADBlOtCUtilt^ * ^port>, <**NiJiDber")} 

reluros the decim:il ec|uivalenl of die binuiy^ pattern on the 
channels of a p(Jrt. 

• Return values 

GetADBIO reiurns four lines of channel type and channel 
value cumbinations (success) or a decimal nutnixr in the 
range 0-J5 {success) or an error string (failure). 

I rying it out 

Make sure ytiu liavc at lea.st one AI)B 1/0 unit hiKjked up 
to your Mac\ nm the Director movie you just created and open 
the message btsx (Note that according to die ADH I/O manual, 
your Macintosh should lx i timed off Ixffore you attach or 
disi:onneci an ADB I/O), Play alxiut with the diree main calls 
ConfigureADIO, SetADBIO and GetADBIO. For each of diese calls, 
make sure you tyjx the Director keyword pul in frfjni of it and 
that you enclose die call’s |>arametefs in bnickets so that you get 
to see die return value in the me,ssage Ik)x. For example, type: 

put cQnflgurcAUaiO (1. 

"digital out", "digital 
**dlgital out", "digital out**) 


No error should ixrur and the XCMD should answer with 0, 
Now be evil and force some error me.ssages, Ibr example: 

put Con figure ADBIO 1, "A","* 

"analog in"i "analog In**.^ 

"analog in". "analog in'* 


Tile return value is an error mes.sage; 

- "Error : Wrong combination of ChannolTyp«» paramcaerss* 

Clearly, the Xf]MD b mt hiipfiy ulx)ui aruilog in on port A 
because only digiUii in and out are allowed. Let’s tiy .soiiiediing else- 

put SetADSIO 1, "A", 5, "high” 

Again die return value is an en'or message: 

— "Error : Invalid Charuiul parameter" 

'fliis time die XCMD is not happy liccause diere are only 
four channels on each jx>rt. Play alxiut a bit more. Don t w'orry 
alxiut the channel values in die channel record returned by 
GetADBIO. For the moment no external electninitrs need to be 
attaclicxi lo the ADB I/O, so never niiiul tlie values of the 
channels and ports. Just try lo get a geneml feel for liie required 
[xirameLers and for the return values of the tluee liandlers. 
Notice how the error messages returned l>y the three handlers 
are actually pretty specific. We will make use of tliis w'licai we 
build our Director object to ctnarol the ADI? I/O, 

A Diklctor Parfjvt ScRim von iiji: ADB I/O 

Now that we have eoveretl the basics of both object- 
oriented Lingo and the ADB I/O, we can write a piuent senpt lo 
control tile ADB f/O. The parent s(.'ripi is called ADB I/O and 
forms part of leslADBl/OMovie.dir included with the 
at'companying code, l-irsi we dis<ijss the handlers concerning 
initializ;Uion and configyrniHin, then those for input and then 
those* for output. Finally we try out the whole patent script. 

Initializaiion and coniiguratfOft 

Listing 1 sliows the parent scripts propertie.s, a liirihing 
iiantilerand a configurePDrt liandler. 

Listing 1____ 

propcniL-si 

property pDEBIfRMossagtf, pbnlt 

property pChannolTypesAList, pChann&lTyp^^fiBUst 

propr^n y pChaiiuelValuesALlst. pCh3mielV-iliJc?sRLlsc 

new 

llilii haiitJkT aotes a diild object and hides sei-tip details. 
lixampkLset oAUBl = new (script'ADB \/ir^ U I RtiD 
P(is.siblc R-nim \'ahifs: An i>bjeei atklRiss (syccess) or 0 (tuUiR»>. 

ofi nev me* llliiit. ibEBUGMessage 

— Requested error rejxjrting. 

set jiDliBlitiMessagc = iOBBl IG.VIessair 

— Wc ;ire wfirking with an inject pa ADB t/O anit, 
set plM-ilJnit 

— These two lists hold die channel U'pes 

— for port A and port U. 
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set pCliannelTypesAList [) 
set pChannelTypesBLiRT = fl 

— IliiTSC two fists hoki ihi" ch;inni'l t’akies 

— for port A itnd port B 

set pChannelVaiussALiat ^ 1) 

SP-t pChannel¥aluesBList “ I J 

— Hie dekmlt initiali/iition of ilic Imrdwyjv is: 

— '‘dij'itiil out" for all cItiiorttfLs of port A and 

— “digitiil in* for all channds of pi>rT H. 

— < jII OMifigOR^ADBIO for N>lh pon A ami ptJrt B 
“ wftli this dcDsult inUcilization 

— AttorUing to tlic ADii IA> riiaiiu;il thb is pnirtkY. 

— llif sellings on sdways lx: changed hicr. 

— lniiiali;te|x>rtA 

— Unit pi fait, p<irr A.all chsinnds digital oyi 

aei iKe^ult “ eoiif 1 ^nr«'rort(inp* "'A","' 

“dig!Tel oyf"» “digital out'** » 
“digliol out", “dlgltsl Dut^) 

if (iResult <> 0) then 

if pDEBUGMessage “ TRUE then put Hesuli 
return 0 
end if 

— Jiiilialiiec port B 

— Unit pUnii. port li.all ctuinncls tligital in 
set IReault = ConfigurePort(me, 

"digital in"* "digitijl 
"digital in**, "digital iir) 

if (iResult <> 0} then 

If pDEBUCHessage '= TRUE then put 1 Result 
return 0 
end if 

rpnirn me 

end _ 

coiifigurcPtm 

IMs handler configures a jxiri 
Exoinpit:: 

c<MlllgurclHHl (oilDliI ."A% 'digital out"."digllul out” 

"digital our/digitiil mir) 

l^jssiNr iTinm values: 

Empty string (success) or an ern>r string (failim:). 

oti contigurePort me, IFort, i Channel I Type, l€hannel2Type,-’ 

iChonnol3Type, [Channel4Type 

— Gin(1gun:AllBlt) returns either an empty string 

— ** * (succesai) or an ernx siring (faUure). 

pui configureADBTO tpllnit, iPort,^ 

IChannelIType * lChannel2Typa. * 
i Chun lie! 3Type, IChannel^iTypeH 
into 1Result 

if IResult “ 0 then 
case IPorr of 

"A*’ I act pChannelTypefiAList ^ 

[ i Channel I Type, lChatioRl2Type, ^ 

IChsnuelIType. iChannel^Typnl "* 

"B*; set pChannelTypeaBLiiil ^ 

L IChannelll’ype. iChaniicl7Type,"' 

IChan nel3Type * iChamie1ATyp e] 

end rsne 
else 

— An (Ttor occiirrrxl 

11 (pDEBUCJKessage^true) then put^ 

“GoniigureADBlO for port" iPori && "of untt**”* 
pUnlt && "failed." 
end if 

return iRosult 
end 


Starling with the hirthtng Imndler, we come across the 
parent script's proj>erties stratgln away. pUnit holds an integer 


with the ID nunitxrr of an ADH I/O device which we pa.ss into 
the birthing handler through the pani merer iUnil. 

pDEBUGMessage is a !>rK>lean property which we can turn 
on to gel a bii more debugging info in the message window. We 
can turn it on through the hirtliing handlers parameter 
iDE BUG Message. Ulie chosen approach to debug itiessages Is to 
reprm nt>ihing while there aa* no errors* Only If there is an error 
will a debug nie.ssage printed to the mess,ige iiox. This is 
bec'tiuse writing to the message box considerably slows down a 
Direcior movie. If them arc no errors we want to avend any slow^ 
downs as tiiey may cause timing problems. 

Next is a .set of four lists. pChannelTypesAList is a list 
which holds the channel lypes lor port A. Similarly, 
pChannelTypesBList holds the channel types for port B, 
pChannelVafuesAList is a list with the channel values of port 
A* Finally, pChannelValtiesBUst is a list wiili the channel 
values of port B. All lists arc initialized as empty lists. 

We use the binhing handler to hide some of the pem sei-up 
details of the ADB I/O. The defauli hardware configuraiion is all 
channels of pon A configured as digiml outputs and all channels 
of port B configured as digital inputs. We match the defauli 
hardware configuration by calling the message handler 
configureRjrt for port A and port li. If you kxjk at configurePort 
you see that it calls Con figure ADB 10 and that il^ it succeeds it .sets 
eitliLT the property pChannelTypesAList or pChannelTypesBUst to 
the ie<[uested cliannel types. If you need otlier settings fcjr either 


GOT BUGS? 

...and you're drowning in paper 
trying to keep track of them? 

You need BusLink! 

• BygLink is a client/server application allowing you 
to connect developers, testers, and support engineers 
anywhere in the world. 

• Intuitive user interface gives you the information you 
need at a glance, 

• Fully customizable database— add the fields you need 
to each project. 

• Custom TCP/IP protocol minimizes network 

traffk“ideal for dial-up connections, 

• CUefii applications can operate *off-line'— allowing 
bug entry and modification even when not connected to 
the network! 

• Cross platform— set up mixed Macintosh and Windows 
environments in minutes with no additional software 
needed* 

• Try before you buy. Download and try risk free for 
30 days from http://www.pandawave.com/bi/ 

A 5 User License starts at $299; that's only $60 per person. 
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The products you need, with the prices 
and service you deserve... guaranteed. 


Power Tools for Program mersi 



Re sorcerer 2.2 


Resorccfiet h ibc goJy support«l general purpose nesourre editor 
tor Maori Losit. Relict upon by thousands Of Mac developers, 
Resoirerer features a wealifi of powerful yet ea^ to use tools for 
easier, foster, and safer etiriir^t! of Matiulosh data files and 
resources. Wliether you have to par^ a picture debug a dula fork^ 
design and try out Balloon Help, create a scripting dictionary, 
tTcate orrti aliased icons, desien and edit a oistom resouire with 
40,000 Tidds in iL create C source code to mr^ a diatog, or any of 
hurxfreds of other resource retaled t^ks. Resorcerer's magic will 
quickly wve you time and money 


VOODOO Server is d version control system for software 
developers using Melrowerks CodGWarrior under Mac OS. 
VOODOO Server and the corresponding VOODOO clients (the 
included CodeWarhor VCS plugnn and the VOODOO Admiri 
applkation) are designed to offer reliable and robust ye*sior> 
control features while minimising the admimstrative overhead 
that usuiilly accompanies version control. If you're a singte 
programmer or managing a team ol developers, version contrd 
ran make or break your project. Do it right, with VOODOO 


Developer's Gj^KitfiRrofessiohal ^ 


C t I Developer's Kit Siandars was developed for everyone who, 
even wiMmiit much knowledge of C + + language or software 
developing, wants to know the C i + programming language 
with applications in the OOSI C+ t Developers Kit explains 
software solutions for C + + developers. prograThmers and 
C+ + students. 


^;Go d ey/arri o r P ro 5 


Sptitlight 


Spotligfii is ihe hrst Macintosh "Automatk Debugger" ir can 
ciiiLomatlcallv locate run time errors in your code and display 
the offending source code litic. Unlike similar tools on other 
platforms Spotlight is easy Lo use. No source code changes 
are necessary for appiiftilion debugging Spotlight can 
auiomatlcally check for wtkf pointers, memory leaks, 
overwrites, underwrites, invalid dereferencing of handles, and 
even toolbojt parameter validity checking spoitiglu krKiws 
Macintosh verifying parameters to over 400 toolbox calls 


BugUnk Solo is a database dedicated lo collecting and backing 
problem reports. Ideal for the shareware developer BugUnk 
Solo allows you to distribute with your software BugLlnk 
Reporter, which can easily be configured to aUow your end users 
to send sUucturcxJ bug reports directly to BugUnk Soto. Promt 
users tor eKactly the information you need, send immidiate 
report confbr mabons, custom i/e a new database to each 
projeett search for related bugs wtfh a simple query. To kill bugs 
dead, you have to know where to find them. 


$189 






CodelAteffiof Professional 5 put everyth ir^ you need for 
software development at your Fitigeriips: project management 
tools, text and resource editors, source and class browsers, 
compilers, linkers, assemblers, and debugger. Release 5 offers 
such features as RAD for .lava, faster compile limes, local and 
remote application debugging, IDb extensibility options and 
ever tighter QC-r + compliance. Additionally, you can create 
appikaboris for Windows 95/9NT and Mac OS 6.x and Mac 
OS X from either host platform, (available in versions hosted on 
Mac or Windows]. 
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Page Charmer ZO 

$139 


WebTen 

$349 


FaceSpan3.0 WrtSpice Animations 

ToolsPlusLite $179 WebSpice 1,000,000 S89 MkUnux 


PowerKey 

Rebound 
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Master the Web! 



VfebSTAR Server Suite Is a complete set of powerful and easy to- 
iuse IJMiemet servers for the Mac OS. Effortlessly serve web pages, 
.host emasi iictoonts, publish databases, and share files all with a 
single applkLillon on one Macf WebSTAR Server Suite is perfect for 
Internet or Intranet serving, single or naolbple sites, smalt I and 
large businesses - it's power and eas<K5fnjse saves any organi^ar ion 
time and money. 


Award-winning Freeway ?.0 Is simpiy the fastesi and easiest way 
to create web pages. Profession aJ web designers worldwide use 
Freeway with its support for CSS and HTML A.O. along with auto 
imago slicing, image optimization, multilingual spell checking, 
HTML Import, builL-ln FTP. and an exdlirig new Actions 
technology to create and rnainiain ieadlng edge websites - all 
without coding a single line. Freeway ships with a 590'P36e 
manual (S/S - Computer Arts MagazmeJ. File maker tutorial, a 
PhotoDisc offer with free images and morel 


MlilUffi 


Funnel Web is the ultimate web analysis solution for professionals. 
Specifically designed for profiling web site usage and monitoring 
customer usage patterns. Funnel Web Is idea! for examining server 
pcfformance and online effectiveness. Funnel Wi'b can analyze log file 
ftnnmats from any server, WtebSTAR, WfebTen, evert Uriis w NT hosted 
ervers. Discover the most popular pages on your site, track server loads 
6i optimize server performance, profile visitors based on organizatim, 
domain name, country, browser, etc. Funnel Web does It all! 


NetBanier offers a Personal R rewall. Anti vandal protection, and 
Internet Filtering- Protect your machine from intrusions by Internet 
or AppleTulk. liKOrrctL passwords and Individual actions are 
logged, you are ulertc'd lo tiostile aclions, and intruders are easily 
isolated. Internet Filtering allows you to be sure hiat password.s. 
credit card numbers, and other sensitive informahon can never be 
exported from your computer - the content itself is filtered before 
any transferl [Rated 4 mice by Macworld Magazine] | 




...and great hardware solutions! 



Add two USQ poets to your older Macintosfi. Connect up to 
15/ devices to the Llniversal Serial Bus [USB) ihaL is 
Apple’s new standard for desktop connettivily. USB mouse 
devices, keyboards, joysticks, game controllers, printers, 
scanners - connect them all to your current computer. 
Installs in minutes! 


$ 35.95 


Any serious garner knows the superiority of the flight joystick. But 
until now, Mac users have been hard pressed to find a gaming 
joystick with the kick-bult power and resiliahce they need. The 
MaeSurfer USB Joystick fits that gap with features fike ^ rrigger 
burtons, rapid fire finger trigger, hat control, throttle, two way self 
centering, and complete customization for your game with the 
included Overdrive software. 
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pon A or B you can call always call configurePort with tlie 
desired channel types after the child object has been cTeatecl 
Note the flow of error messages: if ConftgureADBIO returns an 
error nics.sage, then configurePort returns an enx)r mes^sage and the 
biitliing handler returns 0. Also note die use of die propeiTy 
pDEBUGMessage, If it is tnie we print some error messages to die 
inessitge window. ConfigureADBIO is pieily impoilanL During 
debugging we need to know if it fails and why. 

Reading from inputs 

We will now look at die calks for getting infoniiation froEii 
channels and pons. There are four calls: getChannelDrgftal, 
getChannelAnalog, getPort and getPortDigital. U*tks start with 
getChannelDigital (Listing 2). 

Listin g 2_ _ _ _ _ _ _ 

gciChaimcJDigitai 

Uii$ lianUkT atiiriKS iKc value of a digtlal in pul chitnntl. 

Iix;miplt:gcl(:ii;iiineiDifiil;ii (c)ADJn/A\ 1) 

Possible reairn \'aliies:{} 1 (high) or nn error string (failure). 

on geLCbannelDJgl tal mts IPon. jCbannel 

— Make sure iChannd is within M. 
if iChanneKl OR iChannel)^ then 

set IResult “ "Error ; Invalid Channel parameter"* 
return IResult 
end If 

” Get the ehsirmel types .inU values for tliis port, 
put CetADD10(pUnit. iPort) into IRosuU 

if word 1 of IResult * "Rrror” then 
— GetADHIO rccurnal an error, 
return iResiilT 
disc 

— GciADBlO rciunnxl no error. 

— Lxlraci ihe nclevani line for the tfcsircd cirannti, 

put line iChannel of IResult into iThisChannelString 

™ Oitek whether whether our ehannel is a digital input 
— that is highf low, or noi a digital enpui ai all. 
rase iTh isChennelStrhtg oF 

"digital in/high"": 

— This is a digiUil input anU ii is higli. 
return 1 

"digital in, low**: 

— Tliis is a digital input and it is low. 
return 0 

otherwise: 

— This ehannel noi allow digital in[Ha. 

set iResult = "Error: Channel" && iChannel 

"of port" iPort && "of unit" ' 
pllnit && "is not a digital input." 

relurn iRcsulI 

end ease 
end If 
end 

If you jii.st w^int to look at a single digital input chiinnel, 
getChannelDigital ks the way to do it. First it makes sure iChanne! 
b within the range 1-4, then it calls GetADBIO to retrieve an ui> 
to-date channel record for the port you specify in the iPort 
parameter. Based on the iChannel parameler it extracts the 
relevant line from the channel record. It tlicn determines 


whether the channel is liigh, low or not a digital channel at all 
If the channel is high, getChannelDigital reairns U if it is low it 
returns 0. If the channel Is not a digital input channel, 
getChannelDigital returns an error message. 

The next call we examine is getChannelAnalog (Listing 3)^ 


List.ing.3 _ _ _ _ _ 

giitClianiiclAnaltjg 

Tilts hantticr reairns the v;ih>c of an anabg input channel. Since analog input is only 
possible on poa b. wc do noi need lo pass the pori as a panimcicr 
lixaniplc:g|CtCJiaiuiclAnaJog (oADfll, 1) 
l^issihle reiuni values: 0-2“S?) (success) or an error siring (failure). 

on getChannelAnalog me, iChannel 

— Make sure iCJmuicl is within range M. 
if iCtianneKl OR iChannel >4 then 

set IResult = "Error : Invalid Channel parameter" 
return IResult 
end if 

put GetADBlOCptinit, "B") into IResult 

if word 1 of IResult = "Error" then 
— GctADElO relumed an error, 
return IResult 
else 

— GetADBK) relumed no error. 

— Extract rhe relevant line for ihe ilcsireil channel 

put line iChannel of IResult :Lnlo iT'hisChannelString 

— Check whether analog in is allowed on this cliamicl 
if iThisChannelString contains "analog in" then 
— Tills chajintl dtics alltjw anaiog input 
— Extract its value. 

put char 11 Lo lengihdThisChannclStrIng)"* 
of rrbisChannelSlring Into iVaUieSlrliig 

return value[IValueString) 

else 

— This ch;innel ooi allows analog ii'ipiit. 

set IResult ^"Error : Channel" IChannel 

"of port B of imit" pdnit hir' 

"is not a analog input**' 

return IResult 

end i f 
end I f 
end 

getChannef Analog is the ^malog ecpjivalcnL of 
gctCiKinnclDigilal: it Ls ihe way lo go if you need to monitor 
a single analog input channel, fnrsi ii makes sure the 
parameter iChannel is wiihin the range 1-4, then ii calls 
GetADBIO to retrieve an up-to-date channel record for the 
port you specify in the iPoft parameier. Based on the IChannel 
parameter it extracts the relevant line from the channel 
rec'ord. It ihen del ermines wheifier the channel allows analog 
input* if the channel is an analog input getChannelAnalog 
extracts the channel value, if the channel Ls not a analog 
input channel getChannelAnalog returns an error message. 

But wduil if you need to monitor oiuili[)lc diannels? Calling 
getChannelDigital or getChannelAnalog repeatedly is not very 
efficient, as each time you call them, yoti in fact call GetADBIO 
which reliirns a channel record wit!) the values (T all the 
channels of a port* Reading from or writing to a port too often 
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oin make other input devices on the Ai>B bus aa sluggishiy 
(Beehive Techiiolttgies re<x)mmencLs not to read more than 
12 times per second and not to write more titan 6 times per 
second)* A tnore efficient way to Icxtk at multiple cliannets is by 
meiins of getPort (lisrinj» 4). 

Listing 4 

gfiRin 

lliis liatitJkT Ik>iIi the diiinnti \y\KS :ind tht diannel v'alut^ of thv liipois of a 
partii’ular port.7Tif charrnfl arv srf>rt*d irs pCliijnntnypesAUst or 
ptvIwnndTypcsBljst^deptrntltni^ i>n tht- piirf Tlic channel arc stored jn 
pChanndVahK^sAl.isi or pChannclVahH.',sl}Lisc ttqxnding on iht |x>rL 
TxampIci^rtVirr (oAUHl .“A") 

nHvSiblc rt1um v^ikics: U (success) or m cnor sirm|i (failure), 
on gcilAjri me, IPdn 

set IResulfc - GntAnBTO {pnoltp IPorl) 

tf word I of IReauU «= “Error" then 
— tk^ADBK) rdnmed an cmir 
return iResult 

else 

— GciAUBJO rctumcii rH> cmif. 

— Work cjul the channel wlue and the channel type, 
repeat with 1Channel * I to A 

sot ITHisCliannelString “ line iChannel of iResult 

case (iThisChannelString) of 
"digital inflow"I 

set iChaonelType = "digital In" 
set iChannfilValue ” 0 

"digital In,high": 

uot iChnricielType = "dtftltai In” 
set IChanneiValue “ 1 

“digital out.low": 

set ICbannelType “ "dtgltnl dllI" 
set 1ChannelValue ^ 0 

"dlgUtil out,high": 

set iChanneiType “ "digital out" 
set IChanneiVaiue ^ 1 

"analog ref,255": 

net iChannelType * “analog ref’ 
set IChannolvalue = 255 

otherwise: 

set lUhannelType - “analog in” 
put char 11 to I engthfirhis Channel St ring) nf^ 
IThisChannelStrlng into IChannelValueStriug 
set IChamiGlValue ^ valuei!ChannelValueSlring) 

end rase 

— Store the eluinnel i)’pc and channel value in 
— iheir rcsiKciivc arrays, 
if (iPott "A") then 

setAt pChannelTypesALiBt. IChannel* IChanoclType 
setAc pChflnnelVflluenALini. iChantiel, iChutiiiElvalue 
else 

net At pCliauriclTypeslihist. ichaimei, iChaonelType 
aeiAt pGhannelValuesBList. IChaonel, IChatineiValue 
end If 

end repeat 

return 0 

end if 
end 

In getPort we llniilly make use of the i^roi^erties 
pChannefValuesAList and pChannelValuesBList, getPort calls 


GelAOBIO for ihe desirtxl port. If GetADBIO faiLs. getPort returns ;m 
error mess;tge. If getPort executes suct'cssfully and reairns a 
diannel record, getPort looks at each line of ilie diannel reconci, 
puts ihe channel type in either pChannelTypesAList or 
pChannelTypesBList. and ihc diannel value in either 
pChannelValuesAList or pChannelVSaluesBUst. In ilic pnxess tlie 
values of the input channels are converted to integeni: t) or 1 for a 
digital in[>ut and 0-255 for an analttg input. After calling getPort you 
t'an easily retrieve an inpui dtannefs value by using the standaai 
lingo list access atll getAt. You will see how to use ilie getPort-getAt 
coinlx) in more detail when we put the parent aript intt> action, 
We don’t discuss GetPortDigital in deiiiil here. If you kxik at 
the code, you will .see that it is simply a wmpixT for GetADBIO 
vvilit use of the numlier parameter. It reads all four channels of 
a j>on, converts die Inoary paiiern on ihe pon to a decimal 
numlier and rearms this numtxrr. 

Writing Ui outputs 

There are three calls for setting ouipui <'hannels and ports: 
setChannelDigital, setChannelDigitalDuration and setPortDigital. 
Lets start with setChanne I Digital (Listing 5). 

listing 5 _ 

stiCliaiinPl digital 

lliis liimdltT ti dii^iol uutpul channel high or low. 
lixamplc; NclChnnndDifiital ((^Af)HI,"h''J, I) 
rtturn valuL-ji: 

b (siLrcesjt) or an error string (fiiihirc) 


Cross-Platform C++ 

PP2MFC puts your 
PowerPlant 
applications on 
Windows^ 
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on so t Ch 9 hno 1DI g 11 0 1 bit < 1 Po rt. * iChannel * i Channel Val ue 

- Check whether the toquesLed channel value Is allowed, 
if iChannelValueOD AKD iChaimeiValtieC^l then 

- The requested value is not allowed. 

set I Result ^ ‘*Error; channel value nuist be 0 or I" 

return IRFfiijlt 
end I f 

- Try setting ihe channel to the requested value, 
if 1 Channel Val ue*“D then 

set iResult “ SetADBlOlpUnlt. iPorl* IChanneK “low“) 
else 

set IResult “ SetADBIOCpUnit. iPott. IChannel* "lilgh**^ 
end If 

return 1Result 
end 

setChannelDigital is a cunvenienL way of suiting a single 
digital output channel. Mrst it cha:ks whether the recjuestetl 
cliannel value is 0 or 1. If the chimnel value Ls not 0 or I, 
setChannelDigital aatims an error. Otherwise it uses a call to 
SetADBIO to try to fulfill the request. 

We are not going to cover selChannelDigitalDuration or 
setPortDigital in detail If you Itwtk at the accompanying exxie, 
you will see that setChannelDigitalOuration is similar to 
setChannelDigital 'I'he main cliffeRmce is that the former uses the 
Time parameter in SetADBIO to set a digilal oiilput channel for a 
certain duration. This feature is available on port A r>nly. With 
SetPortDigital you can set a whole port in one go, providing all 
the channels are digital outputs. 

Taking It Aij. for a Spin 

Ok, let's try to put t>ur parent script to tJie test. If you gel 
stuck in this section^ you may wish to peek ahead at tlie trouble 
sh<K>ting section towards llie end of this ailiclc\ 

External electronics 

To lesi the parc'nt .script you need to litxik up some external 
elccUonics to the ADB I/O (Note tliat according to the ADli I/O 
manual, your M;»cini<xsh should be turnetl off before ycju attach or 
(iLsconnect electrical devices from Lite AI>15 I/O), Connc'cl an LTD 
to each cliannel of port A. Hook up potentiometers Ui channel 1 
and channel 2 of port B, Qjnntxl an l.KD to channel 3 of port li 
Hnally, amneri a push-u>-make switch lo channel 1 of |xhi B, 
which connects the cliannel to giound when you press the switch. 
II you Feel unsuiX" aliotJt how to conned the^sc' cx>mponent.s, have a 
l(x)k at the applioirion notes on the Beehive Techn<»logie.s website. 

Initialization and configuration 

Have a look at die startMovie handler in the movie .script of 
lestADBlOMovie.dir. There are only three lines t>f cckJc: 

global oADBl 

openXLlb **AUB 1/0 XCMUs l.O.r 

set oADBl - newtscript ^ADB 1/0"* 1. THUi;) 

Tile tliree lines should loLik hmiiliar to you from the 
testOOMovie.dir and the tesLXCMDsMovie.dir. The first line 
creates a global variable cal led oADBt. The second n^x^ris the 


tibniry with the XC^MDs. 'Ihe third line assign.s to the global 
variable oADB1 a child obje<1 based (»n the ADB I/O parent scTipt 
[ly calling the birthing handler. As I Unit parameter w'e pass 1 (the 
unit ID numl>er) and as iI>EBUGMes.s;ige we pass tnie. 

Before we start playing anniml with the handlers renieinlKT 
tlial we Ux)k the iKvssiiiilslic appniacli to debugging messages: we 
only get to see liad news. No mess;jge is gfxxl news. Now open 
the message lx>x, tlelete any text that liners it, and play the movie. 
If the message lx>x Remains em[)ty tliai Is gotjd news: tlie biithing 
handler iuid the emlxdded calls to configurePUrt fcjr port A and 
|x>n B executed successfully. If you do get an error message you 
shtnild lx* able to llgure out wliat is wrong. After all, we carefully 
passed back die original emir message fttim ConfigureADBIO. 

We can .still get some kind of conf irmation that the birthing 
handler executed successftiily. txa's kxjk at the channel types of 
port A by typing: 

put iKc pChannelTyppfrAList of oADBl 

The message lx)x responds willt: 

i “digital out", “digital aut'** “digital out“,“* 

“digital «jut"| 

That is gtKKk It is default hardware configuration for port A 
wliich we requested in the birthing handler Now Itxik at the 
channel types of poii B, Type: 

put the pChannelTypesBList uAUBi 
- f ‘'distal iu“, "digital In", “digital in“*^ 

“digital in*'! 

AgLiin, dial Ls what we ex]Xxleil. It Is the default bird warn 
ainllgumtion for jx)rt B which we mqut^txl in liirthing handler. 

hrom the electronic comptrnenls y(>u can infer how we 
W'ani the ptirLs to lx: configured. All channels on port A need to 
Iv digital outputs. On port B, channels I and 2 need to be 
analog inputs, channel 3 needs to lx* a digital output and 
channel 4 a digital input* Since the desired configuration of port 
A matches ilie <iefaull configuratiiin we lIo not need to 
reconfigure poii A. 'Ibe desired configuration of port B differs 
from the default conllguration so we call: 

put eoufigure^Fort {oADHl. "fi“* "analog ln“, "analog 

'MigUul out", “digital in") 

1'he message Ik)x slioukl respond with 0 indicating that no 
enxirs incurred. 

Reading fruin inputs 

We will cover the remaining liantllers in die oaler they 
(X'cur in die parent script, left's try reading cliannel 4 of jxjit li, 
a digital input. 

put getCbcumelbigUal {oADBl, “B", 4) 

Providing the jumper on lliLs dtannel is set to puli-up and 
you use a yiuslMo-makc switch connected to ground, 
gelChannelDigttal returns 1 with the switch open and 0 with the 
switch closed. 
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Programming Doesn't Have 
To Be This Difficult. It's REALbasic! 


REALbasic is the award-winning, visual object-oriented 
BASIC development environment for the Macintosh. 

Our application is easy enough for beginners and pow¬ 
erful enough for professionals to use. Whether you want to 
learn for reiurnl) to programming, REALbasic is for youl 

Simply drag and drop user interface elements into your 
application's windows and dialog boxes to create anything 
from a small utility to a large application or the next great 
game—faster and easier Lfian ever before. Experiment, 
explore, learn, and innovate as you build your applications 
step by step while REA I basic handles all the details for you 
so you can concen¬ 


trate on what makes 
your software 
great—your ideas! 




MCMM 




With the Professional Edition you can even access most 
databases and create applications that run on Windows. 

While REALbasic is easy to use, it*s also extremely pow¬ 
erful. Peatures like mu Id-threading, classes, inheritance, 
a powerful debugger, extensibility, VisualBasic project 
import, advanced dynamic recompiling compiler, TCP/IP 
controls, and multimedia tools make REALbasic the per¬ 
fect combirialioii of simplicity and sopliistication. 

Go to www.realbasicxom NOW to download 
a FREE trial version or call 512.263.1233, 

3 REALbasic 

REALbasic is a trademark of REAL Software, Inc. 








Next we try reading an analog input, channel I of port il 

put g.etChannelAtialDg ( aADBl. 1) 

geiChannelAnalog should return a vakie. Now turn the 
poteniiometer connected to this channel and call 
getChannelAnalog again. Notice liow the value of the channel 
changes. Now trv' getChannelAnalog witli channel 2 of port 13. It 
should liehave in the same way. 

'rhe last call for reading inputs is GetPort, Let's call it for 
port 13: 

put &erPart (oADBl, 

Rememher that GetPort sLt jres the channel values of a port 
in either pChannelValuesAListorpChannelValuesBList. Let's fuive a 
look at the property pChannelValuesBList. 

put the pChanrtelVaiuesBList of oADBl 

I'he message box sht^ws a list with four values which 
correspond with the four channels of [X)rr IL We can simply gel 
at each entry in the list through the use of gelAt. 

put g«?tAl (the pChannel.VQlue3BMfit of oADBI. 1] 

gives US titc value of ilie aniilog in[)ui channel 1 of fXMi B, Likewise, 

put giiihl (the pChajuielValuesRlJst of oADBl, 2) 

gives US the value of the analog inpui channel 2 of [xai B. And 
put geiAt (the pChiiiinelVaiuesBLitst of oADBU 4] 

gives US the value the digiial inpui channel 4 t>f port B. 

last access c:;ills to pChannelValuesAUst or pChannelValuesBUst 
mu.st be preceded by a call to getPort. If you do not call getPort 
first, the lists contain old values whkii may differ from the current 
values. Think of getPort and getAt as a cfsiilio 

The last of the message luindlers for Reading from the ADli 
I/O Is getPortDigital. With the comjionents we have got hooked 
up, we ain’t really ry it out in a meaningful way which would 
be to eonven the liinary pattern on a port with ftjur digital input 
channels to a decimal numlx^r. What we can do is show its use 
w^ith the four digital output channels of port A. First set the port 
miU the XCMD SetADBIO, ihen read it again with getPortDigital, 

SetAHRlO I. "A". 15 

put i^utPortlliigital (oALtRl, 

II you play about with tliese commands, you will find tliat 
you can read back from the port tlie value you just wrote to it. 
Note that if you u,se getPoitDigital with a ptiri that has one or 
more channels set to analog in, you will not get an error 
message. An analog input channel will li^ive the value 0. While 
that is not useful in itself, it allows you to w'ork cnit the v^alites 
t)f any remaining digital channels. 


Writing to outputs 

Luckily^ writing to channels and ports is a bit easier than 
reading from them. Let's write to channel 3 of port B, a digital 
outiDiit. Typing 

put setChannelDigital (oADBl, “B'*, 3. 0) 

aims off the LHD, 

put setChajinelDigitai (oADBl, 3* 1) 

turns on the LED. Tiy using setChannelDigitai on port A, 

Next, try setChannelDigitalDuratJon. Remember^ iliis call only 
works on A. Let's Uy it on channel 1 of port A. 

put setChaimelDiglUlOuraLlQn (oADRl, 1. L 10) 

This turns on the LED for 10 x 0.1 = 1 second after which 
die LED turns off 

Finally, diere is seiPort for setting a wdiole port in one go. Enter 
put eetPort (oADBl. "A". 13) 

Tills turn.s on all LEDs on port A, sinee the binary equivalent 
of the decimal integer 15 is 1111. 

Play around a bit more with all diese handlers. Tiy' forcing 
some errors. For exuiuple. try writing to an input channel or 
reading from an output channel. Error message.s will inform you 
if you ask for the impossilile. 

Trolibll Shooting 

Stninge bugs hut no error me.ssages? Or ernir messages wfiich 
(■(jmpletely pu//!c you? Tills .section lists .some ixxssible causes, 

Saftware 

1. Have you enclosed the parameaTs In lirackeLs? All our 
me.ssage handler.s are in fact llinctions, tliat i% they leturn 
values. Lingo expects funciitm.s to have their pa m meters 
enclosed in brackets, 

2, Do the value.s you jiass into the handler match the handler’s 
function prototy[X/'' If they do not, confusing error messages 
may result. 

5. Are all child objects of the ADB I/O parent script declared 
as glolials? If you expect a child object to .stay around in 
memory, while it is actually a local child object which 
goes out of .scope at the end of the handler in whic:h it 
was created* you can get very confusing crror.s. If in 
doubt tr>' using put to print the value of the child object 
to the message box. If you get void you are lialf %vay to 
finding the bug. 

Hardware 

1. Is your port A channel correctly equipped wath a relay oi- 
an opto-isolator? If you need digital output on a port A 
channel you need to have a relay installed, if you need 
digital input you need an opto-isolator installed. Obviously, 
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if you have a relay insLalled on a eliannel and try Lo 
configure it as a digital input, or have an optodsolator 
installed and try to configure it as a digital output, that 
channel will noL work correctly. But a.s the processor in the 
AD13 I/O cannot distinguisii between relays and opto- 
isolators ConfigureADBIO will not return an error string. 

2, Is your pen B channel jumper correctly set to pLtll-up, pull¬ 
down or open circuit? If you need digital input or digital 
output on a channel of p<jrr B, you need to set the jumper to 
pull-up or pull-down. If you need analog input you need to 
disable the jumper (open circuit). If you try analog input with 
pull-up or pull-down you will get erroneous values, hut you 
will not receive any error message. 

Enhancements 

To keep the numl:>er of files Lo a minimum T made the 
testADBI/OMovie.dir self-contained. You may find it convenient to 
put the parent script in an ejcternal cast, so tliat you can easily 
include it with different movies. 

Anotlier {xiint whicli yt>u may have noticed is dial diere is no 
analog output available on the ADB I/O, Howevei; Application 
NfXe 6 on the Beehive Technologies website documeuLs how to 
use Ijodi port A and B to drive four digital potentiomeicrs to create 
four analog outputs. If you h^ive a need for analog outputs you 
may wi.sh to extend the ADB I/O parent script with a 


setChannelAnalog handier which considers each digital 
potentiometer to be a channel. The prototype would look like: 

on setChannelAn?ilog me* iChannel. iChnnnelValue 

Conclusions 

In this article we used objea-oriented Lingo lo create a 
friendly and clean inlerface Ix^Lween the ADB I/O and your 
Director movie. Ot>ject-oriefited Lingo allowed us to likle sca-up 
details in die parent script's birtliing handler and get rid of global 
variables through the use of property variables. If you had never 
done anything like tliis Ix^fore, you don't know half how sfXJiJed 
you are. Director and the ADB I/O fomi a tiuly Mac-worthy 
couple: this is data acquisition Tor the rest of us\ Have fun! 
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SYSTEMS 


By Paul Shields 


Backup Management 


A guide to managing local 
and remote backups for 
your Mac 


iNTRODtfCnON 

When was ihc Iasi lime you lost data 
Ix^eause of a iiarti dnve faikire? I low about 
by aeeiticntally tleletin^ a hie. whose name 
you did noi recognize or fell you no 
longer needed? Have you ever lost data 
because of a lire or ihefi? All of these 
represent real siiuaiions that pt^ople face 
every day. How long l>efore you 
encounter a similar .situalion? 

backups are one of the most criticak 
but often neglecled. tasks in projier data 
management, Uotii home users and network 
adminisirators have lax allitudes towards 
[rackups until the day comes when they lose 
data, es]K‘eially itniTortant businass-ielatcxi 
data, With the rehnemenis in hardware and 
software technologies bac kups are easy and 
lelaiively inexpensive, even for the small 
office and home usei's. 

How' effective is a cotnpany wheix^ the 
list ofcusioniers is lost [xxause ofmaJicious 
activity by a foniier employee or Internet 
hacker? Gin a company sunave if its 
hnancriai system lies in aiin.s Ix-cmise a 
hardw'are failure rendered it useless? As 
systems administrators your responsibility is 
to pnjtcc i c'orponite cx>mpuling asseLs, Since 
data is liecoming one of tlie mexst valuable 
afisets a comjiany has^ impienienting a 


reliable liackup system is essential. As a ]>usiness owner you liiLtst 
take interest in tlie processes used to protect your assets, d here is 
no excuse for being cauglit otT-giiard. 

Backup Tmuminology 

Before beginning a clisciission on implementing a liackup 
systemj we must define some of the cxmimon terms. 

Full backup 

full Isackup is a complete copy of everything tm the 
source drive to the backuf) media. Most users and adminisiratoi's 
iLin a full bLickrip on a w^eekly or monthly basis. 

tncremcnUil backup 

An incremental backup only copies the data that has 
changed since the last backup. Adniinistrators will run 
incremental backups on a daily basis to capture the daia hies 
added or updated during the day. 

Differential backup 

A diffcTenlial backup copies the data that has changed since 
the last full backup. It is impoiianl to imdeistand the difference 
Ixlween an incremental and differemial backup. Administrators 
u.se differential backups to facilitate mure complex tape rotation 
schemes and .sometimes in database environments. 

Archiving 

Too many administrators fail to understand the difference 
between aichive.s and backups, 'they fail to see the powerful 
capabilities of archiving and u,se their nf>rma] backups as artbival 
storage. Archiving is the process of moving data from one media 
(typically a hard drive) to another media (optical disks or taixs). 
Archiving deletes the files from the original kxation. Companies 
may use archiving to store things such as iiistorical financial data. 
Archiving saves s[>ace on hard drives, vvhile retaitiing the al>ility 
to restt>re the data quickly. 


Paul Shields is eurrciuly tlie lechnoiogy Advistjr and Project Manager for a inajur telecommunications firm in Dallas, 
'IX. In liis role Ilinl selects and implements the critical technologies that comprise the backbone of the cumpiuing 
infra.siiucture. He also wiite.s for several publications including AppleLinks hitp://www.applelinks,com/ and develops 
disaster recuveiy plans that niininiize downtime and iiia.\iinize recoveral)ilily. Feel free lu forward any questions or 
comments to him at pshields@c7berramp.net. 
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Picking the Right Media 

Each media type has dramaticaliy different 
characteristics inckiding lifespan, storage capacity, re- 
usal)ility, and costs. Even within a category such as tape 
drives ilie number and variety of optitms available is broad 
enough to suit a wide spectrum of users. One important 
factor in selecting a media is the length of time you plan to 
store die media. Talile 1 provides a lifespan compadstin of 
some of tile most popular [jackup media. 



IJlospan 

MaifiK'lii' Titpt 

1 ■ 3 ttJvwir ta|K! c.xirniling Ihis) 

Mafn^Ltic |)isk.s 


0|Kii:al Disb 

30 

WntLHintr C3>R()M 

30+ 


Tiitie L At*emge of common h^ickup media, Wb is 

s7nc7/v a shelf-life and does noi factor in the nund)er of uses, 


A common mistake is to pick a media type based on the 
needs of today's systems. The data requirements of 
lousinesses are growing at a phenomenal rate estimated to be 
as high as 70% per year by the Gartner Group. A system that 
barely meets the capacity and performance requirements of 
ytJLir current systems will be inadequate within IH months 
and the search will he on for a replaecment. Switching media 
types is an expensive and limc-consuming proposition, 


Tape drives 

Tape is die standard in the l>ackup systems of the 
majority of corporations, 'I'ape offers extremely high 
capacities, excellent performance characteristics, and a 
reasonable lifespan. 'l1ie variety of formats makes tape a 
versatile media tliat can fit in a nurnlxT of envirtmmcnLs. 
Table 2 provides a summaiy' of the most eomnum tape types 
and their specificaLions. 


Type 

Capaoty 

{uiii;4ini]irL‘S.st'Ul 

,Spml 

qinccimpjt*s.si:'d) 

Dnvf (jtijJts 

Media txAUi 

QIC, (Tnivan) 

TH-4; 4 {lU 

my iti on 

IS MH/iiiin 
(i) .MU iiiin 

$3^0 

$550 

$7/Gii 

$'1/<lll 

DAI 

DDS 2; 1 tut 

Dm 5: 12 GU 
or:w^j m gb 

■16 MiVmin 
ttJ MH/min 

IHO MB'min 

$650 

$1050 

$1350 

%2/GH 

$2/GB 

$i,50/GB 

HIT 

Drum 20 on 

DJ:i 7(XK1- 3S(U1 

90 MR min 

300 MB/mi;i 

$2)000 

$3000 

H/cn 

$2l50/(’.B 

AIT 

Aff: .35 GB 

Ami: SOGB 

IKO MB/nuii 

35o MB/min 

$itKK) 

$3tKKI 

$3/Gll 

$2.75/GB 


Table Z Tafn* fy/jcs and specificatiom. Mmt driee 
mannfactHrers offer compression and advertise compressed 
storage capacities that are roughly don hie fheir 
uncompressed capacities. 
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Imagine that. Smart d beautitul. 


Seven port hub M Two Serial antt M One SCSI, 
(standard eight USB ports one serial end 

configuration) five USB pons 


SlMiaen 
USB ports 








One serial 
and twelve 
USB ports 


One SCSI 
two serial and 
four USB ports 


JlkriiftfimiSE 


micTO 


Whvshoiitdyoii 
have, to buy a 
USB hub. then hang 
stuff off of it until it 
looks like something out 
of Edward Scissorhandsl 
Why fumble around 
under your desk every 
time you want to plug in 
another device? 
Instead, try this: A modular, 
stacking system of 
USB hubs, witlj adaj|tet5 i 
for serial, SCSI and more. 
Neat Compact. And, oh yeah... 
drop dead gorgeous. 


€>2tl00 Oflikiri CcMnctattBrtli. M RigKu Rdi^fveit. M Trjdft Earned Ar« ftnotitcfCdTraframarks Ot Daspectivo ManufagtLLrars iistwi. 2014D1P 


Betkin Compononis 
Compton • CA 

310.SSa.11D0*Fax31G.S9B.1111 
Unitad Kingdotn * )lollBnd * Atlanta, GA 

























































¥or a home or small business user, the low exist of the I'ravan 
drives makes them an appealing option. The catch is the high 
media costs ]>lt GB and the slow performance. Althougli 60 
MB/min .sounds fast, a typical hard drive is now 4-8 GB, w^hich 
iranslaies into a hill backup time of 1 - 2 hours. Tfiis long backup 
time makes it a nuisiince and yon are less likely to he anxious to 
give up access to your machine for a few^ hours w^hile it backs op. 

For a large organization, picking the right technology 
depends on the type of backups. Most administrators deploy 
DAT tape drives for network backups because they are less 
expensive and offer good performance and capaciry. AI'I and 
DLT offer more capacity and better performance l>ui are 
expensive. DLT and AIT are perfect for situations where you 
attach the tape directly to a fileserver I^et'ause of the large 
amounts of data on the server. 

The reason DLT and AfT may not fit well in a typical 
network backup is the potentially slow performance of 
moving data between machines. The latest releases of 
Retrospect and O.S H.5 combined with a quality TCP/IP 
network can come close u> Lite speeds needed to use the full 
capacity of a DLT or AIT system* 

To find out why DAI" may be better for network backups 
than DLT compare die difference in performance between a 
lOBa.se-'i' network and DLT drives. At he.st» a lOBase-T 
netw«irk can move data at about 1 MB/s* A DLT writes data at 
a minimum of L8 MB/sec. This gap is even wider widi [he 
new Arr 11 tapes and the pi()posed SuperDLL format. DAT 
drives more closely match the perforniance of a I06ase-T 
network and have a lower cost per MB. DLT is still viable and 
1 use it for network i>at'kups on a regular basis, primarily 
because of its longer iifes[>an and f)elter diiraiiility* 

Another reason to choose tape as a backup media is the 
availai>ility of tape libraries. A tape library is a device that 
contains one or more tape drives along wath dozens or 
liunLlred.s of tape sIot.s, 'fhese systems have a robot that can 
automatically swap tape.s as directed by llie liost computer* 
lape libraries greatly enhance the storage capabilities of a 
backup server. No longer do administrators have to limit 
backups to w^hat wall fit cm a single tape or coastantiy monitor 
the seiver and rotate tapes. The softw'are automatically swaps 
rapes as they fill Retrosix^ci supporus a number of tape library 
systems via the Advanced Driver Kit option. 

Most tiipc drives have a SCSI interface, which f>oses a 
problem for iMac and [}ikW G.3 owners without a SCSI card. 
Until Firewire or USB c’onnections become more common on 
tape drives, users must consider alternatives or [>Liy an atlapter. 
USB is a low-sfKX'd inierfat:e and while adapters exist, tlic 
[XTformance they offer will be disappointing* Firewire offers 
(x.Tfoniiancr levels higher than imditional SCSI, so die use of an 
adapter siiOLtld provide adetjuate performance. Tape drives with 
native Firewme should lx:gin to appear in the next 6-12 months* 

CD and DM> 

Over the last few years, CD and DVD have become 
vialile backup media for small businesses and critical data in 


large businesses* A.s shown in 4 able 2, both CD and DVD 
drives offer good storage capacity and performance with 
moderate media costs. 


Opsidiy (LinaMnprif?ifsed)Spccdt)rtv(’ CostsMcdia Costs 
O) 650 MB600 K: $I/GRr 

RW; SIO/OB 

DVD 5.2GB(2.6Giy.skfc)l300KB/sccJS99 iS/GB 


Tuble 3* CD and DVD specif tcatiom. Vjese media iypes offer 
smaller capacities than iaj^e hut have other advantages that 
make them af^alingfor arcbiml purfmes. 

The real advantage of a CD or DVD is the long lifespan of 
the media. Optical media can fast as long as 30 years before 
oxidalitin slart.s to affect the stored data* Tills makes f)pticai 
media pcTfcci for storing archives of critical data such as 
financials or personnel records* 

One note of caution when considering DVD is that the 
capacity is 2*6 Cifi per sitfe* Sw^itching sides on the DVD recorder 
Is a manual process, which interferes with scheduling 
unatiencled backups. 

Removable drive lechnt>l€>gies 

Zip clrive*s are almost universally available and are 
relatively inexpensive. Jaz drives offer more capacity and 
better [lerformance while retaining a relatively low cost. 
These media though do not offer extremely high levels of 
reliability and are best suited for file transfer, occasional ad- 
iioc backups, and short-term storage* 

Aiit)lhcr problem with removable media is the high custs of 
media* A typical Jaz cartridge coslh $90 and stores 1 GB of data, 
A typical hard drive nf>w tends in the 6 GB range* If we as.stime 
the hard drive is full and that you run a full l>acku]> t>nce per 
week, then the yearly ci>st approaches $2H,00(J. While you may 
lie able to reduce this cost slightly l>y rccycJing c artridge*s, these 
costs do not account for having duplicates of your backup media 
(highly recommended) nor the media used for daily incremental 
backups. Ibis compares |XK^rly to DAT, which under the same 
conditions ha.s a yearly cost of ju,st over $1000. 

One proinLsing technology is the Orb drive from 
CasrleWood <http://www.castlewood*com/>* The Orb uses 
traditional hartl drive media and oilers the fxaential for 
improved relialiility as compared to the Zip/Jaz teclmologies. 
hlDb versions are shipping now, while SCSI, USB, and Firewire 
version should be availaf:jle by ilie middle of the year, Ibe Orb 
solves some <jf (he mtxlia cost problem f^y reducing media cosus 
to approximately one-third the cost of jaz media, While this 
difference does not make die Orl> a competitor to tape in most 
situation.s, it may make it accepUtlMe in .some circumstances. 

Which one is riglit for your needs? 

Most users should avoid removable magnetic drives 
Ix^cause of iheir ilmited capacity and short lifespans* A small 
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busint^s with h few niaeliincs could j>robably do well with tlie 
older DAT tcxhoologie.s (DDS-2 or DDS-3)- Both offer good 
pert'onnance and h>w media costs, 'The newer DDS-4 drives also 
suppoit the oltler tiipes, so when it conies Lime u> upgrade diere 
is an evolutionary path. 

If you needs are Ix^yond the at pacify of DAT, lioth 1)1 T and 
Ai*i“ are exeefleni sokaions. DLT ha.s been in die niarkct place 
longer and is |x>lentially a more stable technology; Sony is 
pushing the AIT standards hard though and the recent AI T 11 
drives surpass 1)1,T in ptTformance, capacity, and media costs* A 
netw^ork administrator will not go wrong with either of these 
technologies, especially for backups of large data servers, 

Media Rotation 

Where (o put your backup tapes? 

Tew' administnitons take the appropriate actions w'hen il 
comes to storing iheir backup tapes. All Uxi often wfien you ask 
the systcnis administrator where die backup taj>cs are, they 
[X)int to a cabinet in their office. Ihis is striedy a inaner of 
convenience and complacenty, Aiiminisiraiors liesitale to send 
die lafTcs olT-stie iK.'causL* as soon as diey do, a user will recjuesi 
a file lestore and diey must luring the tapes hack on-site. 'Ibe 
complacency Ls fx^cause so few network admin isiniiors fiave 
lieen through a major disaster diat resulted in a major loss* Few 
companies have a disaster recovery plan diey enforce and there 
is little incentive Ibr tlie network administrator to tTeate one. 

Home users and small business should invest in a fircpnxjf 
safe at a nuniiimin, A lielter solution is to Find a secure off-site 
storage loc'ation like a safe deposit box at a ItKal hank* Fit her 
way. the clata is safe From the most c’ommon hazards such as fire, 
thefi, or other unfavorable environmental conditions. 

For large ofganiKations, storing the tapes at a remote office 
or an off-site stomge company is ideal When seleiting a site, 
ensure thai die provider maintains proper environ mental 
conditions and takes measures to control access to the backup 
medki* Our local ofFsite storage comp;my wall not reveal its 
eoct lfK:ation under normal t'ircurnsltince. They provide a 
courier pick-up and drop-off service for trans[X)rting tlie tapes 
between .sites. We ship the tapes in sealed Ixixes to ensure thai 
no ont tampers w'irh the <x)nienLs, 

Once you select a sionige locatian, its time to decide how 
often tile media will rotate off-site. 

Developing a rolalioii schedule 

The media rotation .schedule forms die basis of your backup 
schedule. Its at this point that you start asking qiicrsrions like, 
how much data can 1 afford tf) lose? Tliere is no set standard for 
defining a sclicdule but there are a few^ guidelines, 'llie exact 
.schedule you chfxxse w ill depend on the amount of backup data 
and the critical nature of the data. 

The most common method is to do one lull backup jx^r 
w^*ek. usually over a weekend* and incremental l^ackups the rest 
of the week. You have the option of placing die full and 
incremcniai backups on separate tapes, allowing you to ship the 
full backups olT-sile immediately t>n Monday morning. The 
incremental backups from the rest of the week are on a .second 


set of media* You then ship the incremental tapes off-slle on 
Fritiay Ixfore the next full backup, Titis gels the media off-site 
cjuickly and miruniizcs the amount of data at ri,sk. 

The problem with such an aggressive off-site storage 
policy is the inevitable restore request The adminislnitor 
must pull tapes back on-site to complete the restores. A 
potential solution is to bring the older backup tapes back on¬ 
site which may cover some restore retjoests and tiiinfmizc the 
amount of tape shuffling. 

Amnher option is to duf:)hcate capes before sending Them 
off-site. While this method does tloublc your media costs, il 
allf>w;s you to have one copy off-site for disaster recovery and 
one on-site for restores. To duplicate backup media you will 
need a machines witli two tirives, Ketn>spect has a feature io 
facilitate duplication of media. 

T'he ini[K>rtant thing is to keep the VdpQS off-site as much 
as possible. The whole purpose of backups Is to provide safe 
and secure storage for critical data. Leaving diem on-site 
means they are vulnerable to the same di.sasters that may 
destroy the original source. 

Picking a Backlip Package 

There are few' options when il comes to quality backup 
software for the Mae. Dant?. f>evelopment's RelrospecL Ls the 
standard by wliic:h w^e judge (Xher packages. Three versions 
(jf RLarospect are available. The target custEimef for each 
package Is different and selecting the one ihal meeLs your 
needs is relati%'ely easy. 


StoneTable 

You thought it was just a replacement 
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We lied, it is much more ! 
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table code ? What do you need in your table ? 
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Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today ! 

Only $200.00 MasterCard & Visa accepted. 

StoneTablet Publishing 
More Info & demo Voice/FAX (503) 287-3424 

http ://www. teleport, com/'-stack slack@teleport.com 


2000 • MacTI’CTH 








Retrospect 

Uetrospcct is the most compa^heaslve l^ucku]i package for 
iltc lVla<^ and will l>e the packttge administnnors chiK>se for their 
netwt>rk backtit)s. ReircxsfKX'i ran Irackiip ix>rh Ux’-a! and remote 
drives. It also provides sypjxat for l>at:king up Windows 
95/9H/HT machines from your iVlLJciiitosh server. There is an 
add-on package, llie Axivanced Driver Kit, rhar adds siippm tor 
liigivend tape devi<.'es and tajx' libraries. 

Retrospect Network Backup Kit 

'Ihis package includes l)oLh ilic Reirospeci scrvxT an<i 
Reirospect client software. I1iis is the package network 
adminisirakjjs will need in order to rlo centralized backups of ail 
their machines using one or more servers. Each Retrospect client 
rec|uires a unique license and additional licenses are available in 
5, 1(1 and 50 packs. 

Retnwpcct Express 

Retrospect Express is what one might call the consumer 
version of Retnispect, Tlie Express version lacks supptm for 
tape drives, but still has the ability it) imekup to local 
removable tirives or over the Internet (via FTP). These 
features along with ils ease-of-use and low price make it a 
package suitable for home users. 

Backups ior Oni^ 

l*oeal backups are best suiUxl lor home users and very small 
offices where there are tmly ii few iiiactlines. In an office of 
dozens of ustas. there is a ceitain econtmiy of scale to swiiching 
from local hacku|>s to a t eninilized dedkated htekup server. 

Many adininisinuors will also use Itxal backups for stwers 
with large amounts of d;itu to improve backup perfonuance. 
Try'ing to backup several himdretl gigabytes o( data over the 
network is a time-consuming task that may nf)i t'omplete in a 
('onstrained backup window-. 

Configuring Retrospect for ItKral backups 

Keirospect offers an excellent utility called Eiisy Stripi lo 
guide you through the process of building a backup scrip! and 
schedule (Figure 11 faisy Script will automatically run the first 
time you launch Retrospect, Oiherwiscx it is available from the 
Help memi or the Scripts tab in the main window , 


;:.Eiisy5crlpt 



flstmspsct's Eai^Scnpt sata up sctiadulav autorrstic bacitaipA uwig 
your answtni la orra kty quoaUemtk 

Et^Solpt usea tha most toniniin R&lrnspHct fEstunrs. Caniajlt/aur 

Ll»f$ GuiOe for petals on other i&atunes, aicX ttoxt to bifio. 



j Cancel j 

figure i. keims/M/c! IkLsy Saipi tUilily for ^cncTating a backup 
senpt and s^cbeduliK Emyscriin £s avmlahk frum ibelkip menu 
or the Script: iah. 


Individuals and netw'ork administrators will find the 
inicrface of Easy Script easy to use an<I ihorough. Ha.sy Script 
is part of lx>th Retrospect and Relrospcd Express. When you 
start Rasy Script, it ask,s if you are cunfiguring the script for 
local or network backups, 'Ihe next step is to select the 
backup media (Figure 2). 



figure 2. SL'leciing the medui ty/x^ in ketrosf)eci's tJisy Script 
utilitw Retmspect impress mniki not iticiude the tape opUom. 

Pitch stej) in the Easy Script pnxess inckides additional 
information on the options available. After seiec:ling how often 
you want to Irackup, Retrospect asks how^ often you want to 
rotate the media, 'fhe most cominoniy recommended pattern is 
lo backup daily and rotate media on a w'cckly basis (Figure 3). 



figttiv JL Selecting tfx^ medkt nmiion in RetfXis}x.^'L While 
at^tiIahIeJettKslx)nId hctiK^a reasott Uisekxi th* tHf mialion iptiotL 

Aftev selecting the media rotaiion schedule, Reirospet't 
provides a summary' of the intended backup schedule and 
[)ronij>ts the user to provftle a preterred time Ibr backups 
(Figure 4). When you click create, Retros[)eci will prompt you 
Ibr the name of tlie storagesei catalogs (Figure 5). 

I he del'aiilt names am the w'ord ''Storagesef followed by a 
letter (A, Ik C). While this naming convention works, it Is not ideiiL 
A more descriptive miming convenUon w'oultl lx.* appiopriate. One 
suggestion is lo u.st^ the name of the server such as “Financx* Backtip 
St'rver A** and “Finance Backup Stwer B.'' 1best^ names indicate the 
serv'er and backup uXation, making it ULsier lo track w>^lik:h tapes go 
with each server. 'Ihere is a 31<lxinicter limit IxxaiLse of lllename 
resiric:lions in the Macintosh OS, 
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H^ufe 4, displays e4 sumnuin' of the hackt fp 

schedule cuui prompts /hr a pnferred backup time. At thki /Munt 
Retrospect tiill hnild the backttp script. 



Figure 5. Ihe final step is to name the catalog fih^s. RetmslK'cf 
propukfs difault nmmx hut mast admiuistrators will prefer to 
set a more descriptia^ nante. 

Al this (H)int, your backup server is ready io gti and the only 
thing left is to load the media and wail for ilie next scheduled 
liackup. Hetfospect offers more llcxihility u> conUx^l the backup 
pr<K'ess. but niosi lioiiie users anti small offices cun ignore these 
options and use llie default settings. 

Backups i ok Evi-kyoni- 
CoiiTiguriiig Retrospect for network clients 

The prexjess of configuring the server to IxK^ktip network 
clients is almost ideniical exccfH for one step, the configuration 
o(' eacli network client. Ft Jr netwijrk backups, you will neecl a 
unit|ue license key for encli fietrospect clients. License packs are 
available in units of S, 10, anti 5f>, Stitne OliM drive 
manufatnurers will include a 3-usc^r license with liigh-end DL‘1‘, 
DAT, and AIT drives. 

The first step in setting up ntawork clients is it) install tlie 
Hetrnspt*ct cliens coniixtl panel t>n each computer (Figure 6). 
The control [)anel is mostly non-ohtrusive and in my experience 
lias a tremendous ret'ord for .stability and compatiliiliiy with Ixjili 
other extensions and OS updates. Tlie mime of the file has a 
special character at tlie Ixginning tu force it to the Ixmom of the 
control paneLs alphalx.‘tic list thus causing it to load la.st. 


3 zzhzj ^^etrospect Client izi~ E 

Retrospect® Client 

TCP/IP 4 ! 
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O Orf [ Prefererices... ] 
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Figure & Ihe Retroslx'ct Remote control fjane! on each netmnii 
client is easy io iusta/i ami has few comixdihiiity issues. 


daritz 


After installing the Retrospect client on each 
cunipulei, you follow^ the same Easy Seri pi process 
outlined for a single machine environment. The only 
change is ihe proinjTt to find and configure clients (Figure 
7h Retrospect supports AppleTalk andTCfVTF^ connections 
to clients. When y{ni firsi install the Retrospect client on a 
Mac, ii will generally default to AppleTalk. Once captured 
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and configurcrd in litfirospect, the administrator can 
change a client to use TCP/TP. Windows clients only 
support TCP/IP, l‘he primary advantage of TCP/IP is a 
[joLcnlial for a 2X increase in backup performance. 

When you click on a zone. Retrospect sends out a 
broadcast to the zone looking for clients. If you select 
TCP/IP, the server will send out a broadcast to ilie sulmei 
looking for clients. If you want to configure a TCP/TP 
client on anodier subnet, you will need to know its IP 
address or DNS name. 

To configure the clieni, you douhle-chck on it in the 
window and enter a license code. During the client 
configuration, KetrOvSpect will also prompt yt>u ft)r a client 
name and p^ls^sword. Specifying a name allows an 
administrator to identify the machine, instead of relying on 
the Machine (Pile Sharing control panel) name or DNS 
name (PC t lienfs). While you can choose to leave this 
password l>lank, doing so creates a major security hole in 
your backup system. 

The passw'ord ensures that only autliorized backup 
servers attach to die client and poll the client's data. By 
not selling a password, you leave the machine open to 
anyone on your netwwk configuring a copy tjf Keirt>spect 
to capture and backup the data on the client. The person 
w'ith the rogue hackuf:) server now has access to other 
people's data. 

With a password configured, w'hen a Retrospect 
server attempts to connect to the client for the first time, 
a password prompt will appear and the administrator 
must enter the correct password. Tlie server will cache 
ilie password so that it can connect to the client fur future 
backups without having \o prompt the administrator. 

Kor those administrators with sensitive data tliat 
retjulres an even higher level of security, Reirosftcct offers 
the option of encrypUng the data before .sending it across 
the network. This keef^s someeme from configuring a 
protocol analyzer on the network and capturing die data as 
it travels helW'een client anti sener. On newer macliines, 
the performance overliead of encryption is minimal. 


O Cliems on Network ^ 4^;.^:;;^;;. :-:- g) g 



Fifiure 7. 7he interface for adding netuK)rk cHenis mpporLs 
both Appicldik and TCF/IF clkmts. 


After configuring each client, the process continues with 
the schedule and media rotation settings. 

The prohlem with poitables 

The main issue when backing up clients over die 
network is finding an appropriate lime to run the backups. 
Portable computers, which the users tend to disconnect 
from the network at nighty com plica re the issue. The most 
common mistake is to configure the client machines 
during the day when they are all on and connected to the 
network widioul realizing the machine is a portable. When 
backups am at night, the machine is gone. 

The most common solution was to pick a Lime of day 
when there is a high probability of the machine lx:ing 
present on the network such as lunchtime and scheduling 
backups of portables to occur then. Tlii.s melliod presents 
two basic problems. First, there is still no guarantee that 
the machine wall be present on the network. Second, 
lunchtime varies from u.scr to user and many may be in 
the middle of completing a critical task when tlie server 
starts a backup. No matter how fast the machine, backups 
can be an intrusive function that affects performance. In 
the past, we have found that die user reaction to such an 
immediate slowdown in performance is to restart the 
machine in the hopes that it would solve the problem. 
This results in the cancellation of die backup of diat 
machine. The Retrospect client provides a fiarUal solution 
to the prt>blem, by letting a user lowet the priority of the 
backups in the Reiro.sjicci control panel preferences. With 
the faster processc>rH available today, this option can 
allow backup.s to proceed at almost full speed wliile 
mainlaining ii.sability for the user. 

An administrator can carefully monitor the backup 
log,s and attempt to contact tite user in cases of repeated 
backup failures, but is a burdensome ta.sk. Contacting die 
user via the teIe]>lK>tie can be just as difficult as finding 
dieir machine on the network. In addition, just because 
y<ju manage to get hold of them, does mn mean tliey will 
lei you initiate a backup of dieir system immediately. 

Retrospect 4.0 and later [>n)vides a solution to this 
prohlem that I have yet to find an equivalent of in any 
otlier sortware package. In version 4, Daniz introduced 
tile concept of a backup server. Adminislralors configure 
backup server scripts the .same as any other backup script, 
althougli you cannot use rhe Easy Script tool. The 
administrator selects lire backup media, clients, 
sloragesels. and .schedule. A typical backup server script 
miglii look like the example shown in Figure 8. 

Tlie difference is ihai a backup server script runs 
continuously, constanlly monitoring the nelwork for 
clients. The backup server wwks thrtiugh the list of 
clients and checks to see if the client is visible on the 
network. If the client is visible, the backup script checks 
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the amount of time since the last backup (a configural^lc 
option)* If the client is due for a backup, then the server 
sends a notice to the client informing them that backup 
will begin in 20 seconds (another administrator 
amfigutable option). I’he user has a few options at this 
point. They can lei the backup proceed, which is what 
happens by default or they can reschedule it for another 
time. If they choose to reschedule the backup, the server 
noies I he refjuested date/time and makes an effort to retry 
the Iraekups ilien. 


□ Backup Server: backup seiver 
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Figure 8. Jypical backup sewer script hacks up all local 
and nelwork drives to siora^^esal C or D. This script is 
always aciwe hut will nol backup a particular macbme 
more than once a day unless the user requests it. 

Using the backup seiwr script gives the user another 
option. Often a portable user will come in to ilie office for 
a short period to gel a specific task clone. If they know 
they will only in the office for a short time and want to 
ensure backups initiate, they can go to the Retrospect 
control panel and schedule a backup with the server. 
They can specify a certain time and date or simply tell the 
server to back them up ASAP* The server will move their 
machine to llie U)p of ihe list and begin backups as soon 
as any in progress backups complcLe. 

I'lie only problem is explaining to the user die 
difference between ASAP and now. Many of them assume 
by clicking ASAP, llic'y arc telling the server to backup 
them up immediately* Since Retrospect can only backup 
one client at a time, the request goes into a queue. 
Depending on what stage the in-progress backup is at; 
this could mean a significant W'ait. 

While the backup server option is infinitely better than 
the alternatives, it still ftas limits* Tape rotation is not an 
integral part of the backup server script. The l>ackup .server 
will use any tape that matches one of the configured 
storageset opikms. Administrators must l>e careful to load 
and name the tapes before the l>ackup server scTipt 


iniiiates. There Ls no w^ay to ccxle in the script to rotate 
tapes on a weekly basis, so inserting the wrong tape or 
using the wrong name may result tn incremental backups 
using the wrong .storageset* 

A configuration that combines the power of regular 
backup scripts and the backup server might look like this* 
The administrator defines two scripts, one called Full 
backups and t>ne called Daily backups. The administrator 
sets the full backup script to alternate between tapes on 
a w^eekly and runs every Saturday, The daily backups are 
a l>at:kup server script and run continuously Monday - 
Friday. The administrator inserts a idank tape on Friday 
evening which the full backup *script sees and names. On 
Monday the admintstrafor can leave the same tape in and 
store both the Full and Daily l>ackups on Uie same lape. 
The other option is to remove tlic tape, insert a new blank 
tape and name it to match the storageset from the Full 
backup. This ensures that Retrospect bases the next 
incremental backups on the most recent full. 

Summary 

backups are a critical but often neglected task. Proper 
backup*s are relatively easy to manage and the time spent 
in doing backups will l>e worth every minute the next 
time you or one of your users accidentally deletes a 
critical file. 

There are three basic steps to developing a backup 
plan. First, select a media type that meets your storage 
and archival needs. For most home users, magnetic media 
or low^-end tape drives will be adequate. Network 
administrators will want a high performance drive 
mechanism like DAT* DLT or AIT. If the goal is long-term 
archiving than CD-ROM or DVD is a perfect solution* 

Tfie second step is deciding on a media rotation 
schedule and planning a storage location for the baerkup 
media* You should make every effort to store backup media 
off-site siK'h as in a safe-deposit box or other storage facility* 
Wldle Qo-site, tapjes should be in a firepnKif safe. How often 
you rotate backup tapes between sites dejiends on the 
critical nature of the data and the number of restore requests 
you process on a daily Ijasis. 

The final step is configuring tlie software for your 
local machine or on a server that can handle backing up 
remote clients. Once implemented most backup systems 
are easy to maintain. Retrospect tjffcrs some excellent 
reporting capabilities that make it easy to monitor the 
bat:kiip .status of all machine.s. This does nor mean you 
can configure the system and ignore it. Ki 


M.Mtcn 2000 • Ma^Tech 


Backup Managrmeki’ 


43 














PROCRAMMIMC 


Hy Neil Mayhew, Calgary, AB 


Not Your Father’s Resource Template 


A C++ template for 
handling resources in a 


new when they are hinaionmg very prcxiuctivdy witli die 
skills they already liave. 


type-safe way 


To C OR Not to C-*, 

It's very hard lo find a real C 
compiler these days. All the ones 1 know 
of are really C++ eiKiipilers operating in 
baekwards-ctinipatibility mode. So I flntl 
it suTprisinjj that so much code is stilt 
being written in C rather than C++. Since 
C++ is in eveiy way a superset of C lliere 
seems to he no reason for not taking 
atlvantagi^ of at ica.sr some of ihe feainres 
of C++ that make the professional 
[irogramnier’s life so much easier — even 
just the simple ability to dedans variables 
at iheir point of use nillier than at the 
head of the current block or fiindic jn. 

Many progniminers of course do ust* 
C++, although I see a lot of Madmosh 
code that still looks a lot like plain C — 
ranging from .simple things such as using 
prepr<K'e.ssor macros insteatl of const 
literals or inline functions, to using global 
or static variables instead of a hilly- 
encapsuiated solution using objects. 

Why shtiuld tliis be st)? As with many 
things, there are probably a numl>er of 
reajRins. For example’ 

• Most jKognimtiiers find it Itard to 
justify the time to learn something 


• Many of the stinditrd C++ lii>rar>^ fiiiKtioas do ntx fit well with 
the Mac' OS APIs — by using C strings and pallinaines for filers, 
for example — and so it is easier just to stay widi the C-sfyle of 
programming adopted by Apple’s Universal Headers. 

• C++ is considered to lie synonymous with object-oriented 
programming, and ntany people feel that the ntn-iime 
overheads associated with ihis style of pfognimming are tex) 
high in their situation. 

• It is thouglit that using C++ on Mac 0!S requires the use of an 
application framework such as MacAp[> or l^ivverPhini, and 
since Ltie program under tlcvdopmenl is not an application 
then C++ is not approj^riate. 

I plan to show how these and {Jther resen^atiuns alxjot C++ 
are acttially misconceptions. Not everytjne l>dieves liII of these 
things, of course, hui for tltosc still with doubts, or those who 
would welcome the chance to riisccjver more* alxiut stjine of the 
fK)wer-reaLure.s of C++ applied in a Mac OS context, read on. 

Be Wmi That Chainsaw 

Someone has said tliat compared with t>ther languages, C is 
like juggling with knives. Someone else has s;rid that c'ompared 
with C, C++ is like juggling willi chainsaws — awesome power, 
hut riLher nasty when mishandled. Actually, I lliink that C++ fuis 
the capacity lo be much .safer than il The increased ability to 
hide or IcKali^^e dangennis o[xmJtions in a well-tested subuiociulc 
frees the programmer to loncentrate on the logic of the 
application rather than avoiding all the usual “gotchas". Whafs 
more, courtesy of inline funclion.s anti stack-lxusetl ohjecLs this 
ability can come at zero mmime cost — as you will ,see. 


Neil Mayhew w<jrks for Wydiffe liible Translators, a non-pnjfit organization dedicatetl to translating the Bible for liie w^orid s 
400 million pc'oplc that do not have it in their own language. Neil started programming in C in 198.5, ami graduated to ilie 
Mac in 1989. When he“s not at his Mac or trying to !x:at hi.s kids at video games you might lind iiim Hying a slimt kite if it’s 
windy, or throwing a IxKxnerang if if’.s nra. Write to him at NeiLMayhew@Wycliffe.org. 
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Fast Mac ISAM Access 


Many pctsple are amient ui leave ihis work in ilic hancLs of 
ilie providers of applioUion fnimeworks and class libraries. 
11 (>wevf r, the rea 1 gains cume w 1 1 en yui i deveI op data 
aljslractions that are specific to the code in liand. Tit is in turn 
iec[Uiies an undersianding of Features such as template classes 
and smart pt)iliters, which many fK^ople have not yet fully 
^raspc'd anti made their own. 1 ho|X^ that by Lite enti of this 
series of articles yt>ii will feel dial you have. 

I'or those new to C++. I will now tlefine some of t!ie C++ 
jarfton that is used throughout this article, [>ut exfxmenced 
readers may w^ant to skip the rest of this seclitjn. 

Data abstraction is the tet'hni<[ue of creadng an hdealized^ 
interface to a body of data tliat is independent of its actual 
representation. As far as j^issihle, the ahslraclion slu>uld present 
the data as a single. easy-to-descTibe concept. I'Or example, Uic 
abstraction of a stack could \k an object with push and pop 
operations, rather than an array and a next f>oinler 

OivtitKahriti is ihe practice of assigning multiple meanings to 
the same identifier or syiiil>oL In C++ this iLsiially means defining 
sevenil tiiffereni functions with die same name bin different sets 
of aigumenl types, and alli>w ing the compiler to ilistinguish winch 
one should lie called acc'ording to the ty'pes of arguments 
suppIiecL it can also mean that new versions of built-in operators 
(like +) are luring defined, tliai take user-defined tyiies as 
arguments. Note tliat overloading is not usually the s;tme a.s 
{Overriding, since the latter lelers exclusively Hs the redelmition of 
a .su|x.'rc‘litss method in a stjlKlas.s. A single class tnay ovt^rload 
several versions of one of its own inethtxl names, and ovcTloaded 
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Re^l-wnrld datit iiiunageint:iH 
!i{)luijtm\ are typically more complex 
when one examines, ttje pioces, 
diair initially nccngnl/cd by ihe 
majoriiy of database programmers. 
All software projects arc complex 
puzzles comprised of many details, 
m<ist of which arc data-rclmcd. Often 
today’s "DBMS'" solutions sacrifice 
the speed or coniral essential for a 
coin(5clilivc applicalion. 

c-trcc Plus'*, by FairCom, lias 
t>eeii liic clioice of commcTcial 
developers for twenty years precisely 
because it olTers the flexibiltty and 
ciintrol at the detail level lo fit a 


wide variety of data managetuent 
needs. Proven on lariie Unix servers 
and workstations, c-tfee Plus’s 
small luuiprint and exceptional 
performance have also made it die 
engine of choice for profe.ssional 
{kvclopcrs on Mac and Windows, 
c-irce Plus oft'ers sopbi.sticatcd 
ISAM tevel control with which the 
developer may define precise data 
management solutions, making it a 
perfect fit for any development 
project requiring specific data 
handling fe^iture.s. 


C^tSPBe Plus^ offers t^he most; 
mat;ure ISAM soiut;ion t;oday... 
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ofk-niiors arc quite often noi mcthtxLs at all but global functions. 

An inline fmict tort Is dermed just like any other ft met ion, 
anti ttfxjys all the s:imc rules, hut (usually at the coiiqnlefs 
tli.scretion) its axle is generated wherever the Fimtiion is railed, 
rather than just once where it is defined. In this way it is mther 
like a iiiacTti, except that all the nile.s for overloading, aigumenl 
type-conversion and so on apply. It also avoids the typical iiiaeio 
problem of mriItiple-evalnation of ajgumeats, just as with a real' 
function ciilL Whafs more* the compiler is free to optimize the 
generated etxle in any w'ay that is i‘onsi.stent w ith the senianiies 
{)f the function riU, which can {tften bring huge gains in 
effteiency over a physical function atll. Inline functions can 
reduce the cost of data abstraction to zeirt — yielding .solulitms 
that are as fast and cotnpacl as iheir unabstracted cfHinterpait. 

A stack-f7£is(*(J object is one tliat is designed to lx aIkKated 
just like any miter kKnI variable, rather tlian by a heap alkxalicyn 
via new. Ibe sfyace^allocaiion (werhead i.s effectively zercy (lioth in 
iitm‘ and heap space) and the <inly execution overhead is in the 
eoiLsiaicior- and destruaor-aills for the object. Very often, these 
calls represent code that would need to be executed anyway, for 
example to initialize a data stmeiure or free Mime memory, and 
the compiler Uikes rare of calling this code at ics pnyper lime, 

A tempkite class Is a generic delinition of an inlinite family of 
n'lauxl ciassc's, in which atch family rnemlxrr is asMxiaic=x.l with a 
different auxiliaty- tlini ty'pc*. lliis asstxrkiiion Is made ]>y sulisiituting 
the sjxrific data type for a Ibmrial aigunient of the template 
definition. Yov examp^le, a stack lenipbite would define the lx.*li;tvior 
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portable and offers unequalled 
control. FairCoin has been providing 
database solutions to the commercial 
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of n faniiiy of smck classes, and each f^ily member (tilled an 
imtarUiatton of the template) would be a stack duss sit}ring some 
ptirtic'ular type (char, double, Person*, etc.). Template arguments are 
spec ified fxitwccn wcxlgcs o, and subsequently within the template 
dcTinition they can be used just like a typedef name. Ttie metfiods of 
a template class are iLsimlfy inline, altiiougli they don't have to be, 

A smart fxyinler is an object tliai has the syntax and 
semantics of a pointer, through overloading the * and -> 
operators for that class. Hopefully it will also liave behavior that 
is useful enough to Ire considered smart! For example, a smart 
pointer class can l>e defined tfutt auiomatic^afly maintains a 
reference count on the objects l:)eing pointed to. ^Smart pointers 
are almost always stack^based objects, or data members of some 
other objecL They arc designed to be passed around by value 
ratlier than by reference (otherwise the reference counting 
would not work, for example). A native C++ pointer ts often 
contrastingly referred to as a mwpointer 

Cast Yoim Cares Away.,, 

Casts are a fad of life in Mac OS programming. Although 
they are messy and error-prone, they can’t lie avoided. For 
example, GetResource returns a Handle, but thi.s must Ix" cast to 
whatever structure represents the data Ixfore using it. However, 
a mismatch Ixtwecn the actual contents of the resource and the 
cast tliat is used is usually disastrous. 'PIk! soptiisticatcd tyj>e- 
matching features of C/C++ are designed to hclf) you avoid diis 
kind of thing, but a cast circumvents these checks completely. 
Whilst good use of C++ cannot remove the need for a cast 
st)mewhere in your code, it can at least confine it to one 
carefully-chtxsen place. The result, as you will see, is a much 
r'learer and neater program, as well as a safer one. 

As an example of using resources, we will consider a ctxie 
fragment that reads and writes high-scores from a preference file 
(very loo.sely based on July's Started column). The first 

thing is to define a .structure that represents the layfiut of the 
data in the resource: 

Listing LI: Resource smicmre _ 

Store 

sirtjct Score 
I 

UlTjt32 score: //What ilw ptiycr M;oiTcd 

Boolean used: // Whetlier this entry b in use 

S t r 2 5 3 name; // Ttic player's name (varialile-Icngth) 

The code to read and display the high-score list might look 
as follows; 

Listing 1 .2: TradlUonat a pproach__ 

ShowScores 

const ResType kScorcType - 'Scor‘: 

void ShowScoresO 

I 

int n “ Count1sourcesCkScoteType): 
for (Int i = 1; 1 <“ n; ++i) 

Score*' S" (Score")GertIndResmircefkScoreType, i): 


it (ts) 
break] 

if ((•*£),used) 

//Append (* *^). score and (* *s) .name to score window,.. 

RclcaseRcsourcet(Handle)s): 

I 

I 

Gcx>d practice has Ixen fiilkiwcd in using a symbolic 
definition for the resource type (although 1 have seen plenty of 
code diat does not). However, note that: 

• two cases are used (ugly and error-prone) 

• there is no way to easure that the cast and the ResType match 
(in the call to GetllndResource) 

• the resource-type symlxil is used in two different places (an 
(ipptiitunity for mistakes if the name Ls ever changed) 

• the cumbersome (**). syntax is needed for accessing die data. 

How could we make use of C++ to overcome these 
deficiencies? Bear with me for a moment and lake a look at one 
possible end result: 

Listing 1,3: Alternative approach_ 

ShowSciHt'S 

typedef ResHhndleCScore. *S€Dr‘> ScoreResource; 

void ShowSegresO 

I 

Scoteftesource s: 

Int n = s. Count! (3; 

for tint 1 ^ h E <- n: ++i) 

I 

B .Getllnddl: 

If (!s) 
break; 

ir (fi >LJsed) 

//Append s->?)Caiie ami lo score window, 

S.Release(): 

I 

I 

Tlie symlx>lic definition of the ResType constant has ixen 
replaced with a typedef representing the inslantialion of a 
template (Til explain this more fully in a minute), and ilie 
ke.source Manager AJ^I’s have l^een replaced with methods, fn 
contrast with the previous list of deficiencies: 

• no cusLs are visit lie 

• there is no pussibiliiy of mismatch lietween ResType and 
pointer type, as tfie relevant infoniiaiion is leaked together in 
the typedef 

• die ResType does not need to appear anywhere except in 
the typedef 

• the *> oper^itor is used in place of (**). 

Now a word aboiu the typedef. A Lemplale class called 
ResHandle Is defined in a liciider file, and is iastantiated 
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{paninieterized) wilh two pieces of infomi:itkm. One is the type 
of iJie cliim ih'M tlic liancile will refer lo, and the other is the 
ResType constant dial is asstK'iated witli Llie data. Not iriany 
people realize that template parameters can Ije ctmsiant values 
as well as type* names, but this is a very powerful feature of C++ 
that we will return to later Finally, llvi.s instantiation of 
RGsHandle is given the synilK>lic: name Score Resource. 

You may also Iiave realized by now that ResHandle is in fact 
a ^smari pointer’. It overloads die * and -> operators to |>erform 
the douiile-dereference for you (just as AiPW C++ used to, W'ay 
hack). Some [leople would no doubt tlismiss tins a.s syntactic 
sugar' liut 1 am in favor of anything that makes die code clearer 
and simpler Of course* in one sease it makes die ccxie more 
obscure, because it hides the fad that a handle is involved at aU. 
but I think this is a price wonh paying* especially if the 
ResHandle template is used universally throughout an 
application. Note that Ixnh . and -> arc used on the 
ScoreResource objeti: the former calls metlxxls that affect or use 
the value of die handle* and the luner allows one to acce.ss the 
object that is pointed to by the handle. This duality is very 
t:ommon with smart pointers, and it is impoilanl to understand 
the two different meanings clearly. 


return relnterpret_ca8t<Ty|}e**>tb): 

I 


public r 

// (’j£>iisrnictor - iniaaltist: the handle lo icno 
KEDiRandlet) ; bCO) II 


//1 [sing ctJitipilcr's c(jpy constructor and a.ssignmcni operator 
// t’sing co^mpilcT s destnicior 


// Dertferencing ojKraionsi 

Typr^* operator C) I return 'downCant (h): I 
Typei operator * 0 I return *•dovnCasith): I 


// Convention (>pcrjiors 
operator Handlet) 
operator Type**() 
Operatror Type* j) 

// Stauis t>|X:nuors 
bool operator I C) 
operator bod () 

//Mac aSAl% 

bool Anocate^Si^e n 

I 

h ^ MewHandletn): 
return MeraErrorO 

] 

bool Resize(Si3!C! n) 


( return b: I 
I rerurn downCast(b): I 
I return *downCaat(h): 1 


[ return h Q: 1 
I return h t“ Or I 


- filzGof(Type)) 


” rioErr: 


SetHnndleSlze(b , ti): 
return HemErrorO = noErr: 


Under The Hood**. 

We can now lake a kx>k at die ‘w'lzaixliy’ lx:hind the 
ResHandle lemplate* although 1 hope yoiill agree that in g(KKl 
C++* like Madi, eveiYthing Itxiks very simple once you have 
chosen the riglil definitions to use. 

The original designers of the Mac OS came from an object- 
oriented Inickgroiind, and this is reflected in the fact that many 
of the Mac OS APIs are object-iirienced in concept if not in 
syntax. For exitniple* a resource handle ‘‘is a kind of liandle. All 
the calls dial ran lie [xrrformed on a Iiandle t:an lie [lerformed 
on a resource handle, and lesource handles add a few extra calls 
of dieir own that can't be jTerlbniied on a regular liandle. So it 
would lx: nice if any C++ Ireatment of resource handles could 
reflect this irdieritance relationship. 'Fills would have the added 
lx:neflt of allowing cnmplle’time detection of passing the wrong 
type of handle to an API — vastly preferable to discovering it at 
run-time, or even not discovering if at all. 

So* tile definition of ResHandle acaially inhcriis fmm a more 
basic tlefinition of MemHandle. Well take a look at tliat first (listing 
2*1) and tlien ptxx:eed to ResHandle alter tliat (Usting 2*2). 


Listing 2.1: MemHandle template class 

MemHautlli: 

A -sman-poinier icmplate thar oicajj^iubtcs a a-Kulaf Mat OS nittmir)' handle. 


leinpiate<clasfi Type> 
class MemHsndlc 
I 

Hundle h: 


// Basic ca^s - up/down icJeni lo the class hierarchy 
static Handle upCflfit(Type’* t) 

I 

return reinterpret cast<Haiidle> (t); 

] 

static Type** downCaslUUindie h) 

I 


bool Disposed 
I 

DiaposeHandleth); 
h “ Oi 

return MemErrorO 

r 

// cic etc. 


noErr; 
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OSErr Error() 

I 

return MemErrort): 

1 

i: 

MemHandle explained 

This template contains all the bask* macliiner^^ needed Lo 
manipulate handles, although lor simplicity of illustniLion quite 
a few niethotis liave Ix^en left out {dt>wnlmd the s{)iLrce code to 
see a slightly fuller implemenUition). It is defined as a template 
so that it can used to represent any type of ckita that is held 
in a handle, at ling much like a raw pointer. Ihe tompiler is then 
able to enforce proper type consistency throughout the prognim. 

The template pjiratiieiei, Type, is ilie data type of the 
contents of the handle. In (itir example, this is a Score. When 
used as a piiinier, with -> or *, a MemHandle has ilie syntax anti 
semantics of a Type^ 

As far as tlaia is cimcerned, MemHandle is just a wrapper 
for a raw^ Mac OS memory handle. A MemHandle, w^hen 
allocated on the stack, takes up just the same amouni of 
space. The data member, h, is declared protected so that 
suWasses (such as ResHandle) can easily access the raw 
handle, It could have been defined as a Type'*, but the API- 
meliiods (of whicli there would be many in a full 
inifjlementatron) are greafiy simplified if it is just a Handle. 

All the ra.sting is perfornied by two static, inline methods, 
upCast and downCast. 'fhe naming convention is based on the 
idea that a cast from a suk lass to a sLi|x.Tclass gt>es up the class 
hierarchy, and vice versa. All hough a Handle is not actually a 
.superclass of a Type*\ the concept is the s;ime. Imernally, these 
two methods u.se reinterpret_cast rather llian the traditional C 
c'itsi. I'his Is now prefeiTed in C++, as a way to distinguish the 
ccxle s intention from tether uses of ca.sitng (such as static_cast, 
dynamlc_cast and const^castf by wmpping ifie castittg inside 
tlie.se methcxls, all the other methods are made considerably 
cleaner and ea,sier to read. 

MemHandle defines a single constructor wiiii no arguments, 
and allows tin* compiler to supply a standard copy-ciinstriKtor 
(used for making a new' MemHandle from another) and 
assignment o[XTJior (used for overwriting one MemHandle w ilh 
amMher). 5)ince the only legiimate wiiy to create a non-nil Handle 
is i)y calling NewHandle or by copying another one, it makes 
.sense to have these as the tmly constructors for MemHandle. If 
you want ti> allow <i>pying of raw handles into smart ones, it’s 
[irobably Ixst to dcTme a method (or explicit constmcior) that 
takes a Type*', to avoid attidenUs, It’s not wase to deHne a 
destmcLor that ailLs DisposeHandle beauise in the absence of 
relerence^coiiniing there i.s no way to be sure that another co[>y 
of the handle isn’t still in use .somewhere. 

Whether or not yon define them yourself, you slit^uld 
always give thought to The fimcLmiental four” whenever ytui 
design a new' cla.ss: tJefauit comtmetar (no argumenLs, or 
argumenLs with default values), copy constmclor, assignnieui 
olx^rulor and eJestmetor. ll’.s also a good idea to consider how 
you wxmkl define a lcs.s-than operator, esjiecially if you ever 


want to store your object in an 8*11. container. If the cof)y 
constrictor or the assignment opentlor does not make sense for 
your object, llien make it inacccssilile by declaring it private and 
never implementing it do stop the compiler implementing it for 
you). That way you get an emji either at conipile-time or at link 
time, hut never at run-time. 

Hie dereferencing operators are just simple calls to one of 
ihc casting functions, aldiough the existence of these methods Ls 
the key to making our template lx: a .snian pointer. The puqxise 
of eacli Ls fairly self-evident, and the reason for the different 
return tyjx^s is purely conventional. 

Conversion operators allow one to .supply a MemHandle 
whenever one t>f these other types is expected (such as in a 
parameter to a function or API), and the compiler will call 
ihe appropriate conversitm ccxle. Note, though, that bceause 
all the methods are inline, everything is resolved at compile¬ 
time and in the case of type-conversion no additional code 
will actually he generated. 

Hte staais ojK-rators simply pnivide a convenient way of 
checking whetlicr the handle is cuiTently nil or not. StiUeoients 
such as if (mh) ... and if {!mh) ... will work as expected. Note that 
this is mtf the s;une as s:iying cf (mh = 0) ... or If (mh k 0) ... 

t fie rest of the cla.ss is API methods, and I have included just 
a few of tliese for illu.straiion. Note iliat ihca' need.s to Ix" a way 
to s[X‘ciry a size using Allocate anti Resize sini'e Type may actually 
have variable length (a.s in our Score example), 

lasting 2.2: ResHandle template class 

ResUandX 

A smjin-p(jjnttT U’nipUu- itijit cncap,sulna?i a M;k a'StHiav handk. 

tenipiate^L’laRjT Type. ResType kResType) 
class ResKatidV : public HeDiiJaritJlp<Type> 

I 

public: 

// Coiisiruciors.cic. — using dtliiuilf« 


// Mac OSARIs 

boui Cetdnt id, ResTyp^ type ^ kResType) 
f 

h = GtnRftBQUrceftype, id): 
return StesErrorO ^ noErr i 
t 

bool CexltifU Id. R(?sType type kResType) 
t 

h = G^tlResourcclrype, id): 
return ReeErrorO ^ noErr: 

1 

bool Geilndfint i. RasiType lypfi = kResType) 
( 

h ^ Ce 11 fid Resou tee (type, i): 
return ResEirorO = noErr: 


bool GptUnddnt i. RenType type = kRenTypn) 

I 

h = Gct 1fndResourcettype. 1): 
return HenErrorO *“ noErr; 

I 

static stiori Count(ResType type = kResType) 

I 

return CountResaurCUS(type): 

I 

static short Count1(ResType type = kResType) 

1 

return Cuun LIResources(type): 

I 
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void ChaTigedO 
I 

ChangedResourceCh)^ 
I 

void Rele&set) 

I 

Rc!li;aceKcsourcc{h); 
h = 0; 

I 

// cic. dt. 

static OSErr Error() 

\ 

return RpfiKrrorOi 

I 

t: 


KcsHandle cxpLiined 

Apiin fn)ni one siiliikny tn rlie template puramevers, ResHandle 
(List atkis sonic extra API melliocls. All the bj.sif fim£iionaliT>\ anti 
tlie tricky operator overloading, is inherited Troni MemHandle. 

ResHandle ha.s iwt) lemplate arguments. The first Is simply 
passetl on down to MemHandle. untl is iLseil tt) define the data 
tyix" of the contents of the handle. The second, however, is noi 
allowed to lx* a class or type mime at all. It ha.s to lx a value of 
tyfx ResType, and a (‘onstanl one at that. As we have seen from 
the Score example, this would nonually lx a liieml fonr-char 
txxle supplied as pait of a typedef: 

typedei ResHsndieCScore. *Scor'> SecreReflource; 

So this consiani value acuiaily Ixcomes a [lari of the 
datatype defined hy the typedef. This may seem a litlle hard to 


grasp at first, but a couple of other examples may make things 
clearer. In traditional C, it is possibU; to WTite: 

typedef char Acronyin[4)i 

Arranyn* myljKl; 

riien the comjxler knows iliat Acronym means “army of four 
c haracters," and when we write nr}yUst++ the compiler knows to 
increment the binary value by 4. So the constant value 4 
Ixcomes a pait of the type definition. 

C++ has extended this concept, mostly to allow generic 
implemeniaticyn of fixed-size arrays using a template (useful for 
Pascal strings). So in C++ we could write: 

teJnplaTi»Cirir ncharc) Var inbU*Acrorjym 

1 

rtmr ilalutitchuri^] ; 

1 : 

typedef VariableAcronYai<^> Acrnnyffl; 

Of course, the coiLst:tnt-iem[)laie-paramelcr mecrianism nin 
ix nsed for any purpose* we like, and in this case it conic's in 
extremely handy as a way of rmirding the ResType value that 
Ixiongs with a particular iy|x of tvsoun'e handle. By making it a 
template parameter, we nevei' Itave to store* it at niniime along 
with the handle, bts^iuse everywhere it is needed wxean supf>ly 
it as a compile-tiiiic constant (kResType). Of course, the value of 
kResType will Ix different fur each instantiation of the templaie, 

A tlilfeteni value for the resource type can however lx 
[irovidcLl at mntime by supplying an optional second aigument to 
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iJic Gel iiiciIkxLs. Tills Is lo allow for resource types tliat sometimes 
masquei'ade us a different ResType (owner restaumes, f{jr example, 
which are really 'STR ‘s). To gel the owner lesourcc, you would 
declare a variable ni ty|K‘ SlrResource and pss tiie iipplication’s 
signature to the Get cill. 

The Count methcxls have lx.'en defined static. Ixxrause tliey 
donT act on any particular liantUe. Tliey do, however, till in 
kResType for us, which is kindy. In the Score example that we 
ltx>ked at earlier, the declaration of the SctxeResource handle was 
moved up out of the kx)p so that we could use it to cxxint the 
nyiiilx:r of scoi'e lesources. We could, of cxxirse, call Score Resource:: 
Gounti directly, hut diat would lx* more verixise and more enor- 
]')rone its the name ScoreResouroe wxjliIcI liave to apjxrar twicx\ once 
in the melluxl call and once in the himdle declaration. 

Tim Fimal S<x)re-„ 

So how dtx.\s our solution stack up against tlie list of pioblenis 
given at the start of tills article? 

• T6ikififi time io kwit somcihiH}^ mii^ I ho[x* youTl agree that the 
Lec!uik|ucs 1 liave outlined do firing teal benefits to our code.) 
hope too yrnili liave foun^i that learning something new dklnT 
take up all that much of your valuaf>le lime. 

• Lwir{if imlh the Mac (XS AP!s: the C++ that we wrote gets itlong 
just fine witii the APIs, and mikes lliem a lot easier to work with 
into the baigain. 

• Riin-Hme omf^cack using (air ResHandle temiikite uses no moie 
rriemoiyx generates no more code, and executes just as quickly 
as our traditional solution. Actually, the* consinicior docs 
redundantly initialize the handle to zero once, at llie stmt of die 
function, hut Uie ciaujiilcrs o]>Uiiiizalion,s lemove this (as shown 
by a dlsaxsembty). 

• fratmmniis: w relin! on noiliing more dian die 
TJnwerial Headers, and yet managed to write some fairly' 
cifective C++, Tlie low run-time overhead meaas that this code 
cxxikl lx usetl without problem in a ccxle resourc::e or system 
extension (an entire example application Is 22(X) bytes code and 
1800 bytes dam when built for PPC). Equally, this ccxle would fit 
quite comfbnably into any fr:imework4xi.sed application 1 (k>. 

Inc idcnuilly, Powei Plant and MacApp lx)!h have suites of 
utility classes that can be used independently of the rest of the 
framework, and you .shntikl check ihese out befoa.* rushing 
ahead lo reinvent Ux> tiiany more wheels. However, it is haal to 
find a generic soluticun that fits eveiyone's needs, .so rhere is still 
great Ixmefii in being able to develop your own utility classes, 
or customize ih<j,st; written by cjtlier^s. 

Tlie ccxle {>resenied here Itas netessarily lieen radter short and 
simple, of course. It Ls intended only as an ilktstniiion of the kinds 
of things tliat fxxtrme possible when the full power of C++ is 
brought to bciir on die task erf’ pn>grariiiTiing for the Mac O.S. In a 
future article, Fll present a liglitweiglit tTstfe;iiivsly1e class that is 
based anxmd Pasc'al strings. As well a.s Ix^ing invaluable for 
generating text mes.sagc’s tJjta need lo ap[X"ai^ in tire Ul, it provides 
furd ier illastialion of the advanced capabilities of C++. 
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By Kas Ibomas 


Dynamic PDF Made Easy 


Ifs simpler than you think 
to generate custom PDF 
documents in real time 
using Perl and CGI 


I\)rlable DiKumeni hVinmt 
(PDF) has won universal acclaini as 
(ioc'ument incerehange format, liecause of 
iLs aljjlity l,o deliver graphically rich, 
structured conient consistenily across 
multiple c^perating environments. Because 
of its strong support for vector graphics, 
font embedding, liytx'rlexl links, and other 
advanced features, PDF is a powerful, far- 
reaching dfx'ument standard. But that also 
makes it a relatively complex smndard. (For 
details, see die SeptenilxT 1999 A/fflcTedt.) 
PDF's complexity, in turn, lias discouraged 
itutny web developers from attempting to 
write PDF files dynainically, at the sender. 
Automatically generated IlTMl. pages are 
common; but wdien was the last time you 
saw an autogenerated PDF web page? 

U turns out that witli a little 
foreknowledge of PDF’s internal w^orkings, 
and a gcxxl grasp of CG] fundiimenTals, it's 
not tliat hud to put trjgetlier server saijHs 
that wdl generate PDF on demand. ’Iheie's 
no cjueslioo that dynamic PDF can be a 
challenge to do rigiit. But if your dynamic 
d<K*ument needs are nxxiest (for example, if 
you'd simply tike to be able to genenite a 
custom “Thank You" f^ge at nm time) and 
ycKir Peri skills are passitble (i,e., you've 


graduated from writing Ttello Vtbrld" to generating the mitch mtim 
impressive string Internal Server Erior"), you can automate tlie 
serv ing of cxLsiom PDF pjtgt^ with surpifisingly little eftoit. In fact, a 
Perl script comprising no more than five or six tlo/en lines of axle 
will ^t you started. 


Our StratfXiY 

Our stmtegy will Ixf simple: We want to be able to collect an 
arbitrary glob of Utser text" from a w'eh form, and convert that 
text to a PDF page served bat^k to the user via H FI'P, suitable for 
viewing in a browser eqiii[)()ed with tlie free Aerobat View^er 
pKtgdn. For simplicity's sake, well start by omitting any attempts 
at vector graphic s, colored text, rotated text, styled text in various 
point sizes, etc (Bui 1 hasten to add lhal Ix^fone this article is 
finished, we're going to Ix^ c.lo]ng all of those tilings and more.) 
Ftx starters, we just want to serve the user's w^ords back to him, 
at any convenient point size, in black and while, on a letter-sized 
PDF page. For sake of convenience. weVe also going to generate 
the "dauj collection" form and our PDF reply from one tmd tlie 
same Perl script. That way, we don't have to keep track of 
multiple documenis: an HTML fomi, Pert scripcs, CSS stylesheets, 
etc. If you w^ani to add that complexity^ to the picture yourself 
later, so lx it. Here, we're going to keep things stone-simple. 

1 might point out that "live'' copies of the dynamic-PDF 
script.s developed below can be found at 
<http://v\AWW.aaoforms.com/dynam icPDF.htm l> (which is a portal 
page with links to several working scripts). 

I also want to stress that when we're done, the PDF pages 
we will have generateri can be saved to disk using your 
browser’s Save As Tea lure. CReiider w'on't save the clocs, bur your 
browser wilL) Thus, we will have achieved the Holy Grail of the 
PDF wxirldi writing PDF without using Distiller or Acrobat. 

Once we've gotten onr basic apprfxtch nailed down, we'll 
branch out into fancy features like colored backgrounds, 
stniked/filled paths, rotated text, styled text, etc. But first, a 
deKmr into (he land of PDF internal smiaure. 


Kas ITiomas <ki@svgcentral.cojn> consults for Adobe Systems and writes a regular coluinn alK>Lii l*DF-aiated progranmiing 
(covering JavaScript, CGI, dynamic Pf)r, aixl related issues) for www .acroronns.com. He has been programming in C and 
assembly on the Mac since MC68000 days and rememhers wrien the MacOS ran in lilack-and-white. 
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PDF AT TllT SlIllATOMlC LeVEL 

InicmallyT u 1M>F filw a>asists of plain-ASCH object 
descriptions, following a notably Fc^jstscript-like (i.e., postfix- 
nfjtaiion) syntax. All I^DF files have a header Cconiaining version 
inff>rmLition). a crfxss-reference (or 'xref ) table containing offsets 
to die various objects tliat make up the file, and a tniiler 
containing references to the rota objetl as well as the byte idTset 
from the start of the file to the beginning of the 'xief table. <See 
ixiy story in .see the Septeml')er 1999 tAacTech for more 
information,) llie fonnal PDF .specifirationj available online at 
hitp://partners.adohe.et>ni/asn/develt?per/PnFSAlV/Pl>FSPEC.F 
DF, deserilie^s the relationships lietween PDl- objects (and the 
meanings of various clictionaiy “key" entries) in comprehensive 
detail if you re interested. Bui we’re gtnng to skip all tliaU 
l)ecause most of it Is not nece.s.sary For what we're doing. 

It turas out you can I’Jend (or even break) a lot of the “niles" 
.spelled out in the PDF spec, withoiu making Acniliai Reader 
unhappy, if you know a thing or twt) alxxit PDF internals. An 
instructive exercise in this regard is to make Adolx;'s Distiller 
pnigram generate a small “Hello World” type of file, then 
examine the file in a lexl editor—and iiy^ to find superlluous data 
in it that can l>e removed. If you tiy this, you will quickly 
discover that /Info objects, for example, ctmtain meta data alxiiit 
the PDF file (such as the dtx'’s auilair, subject, producer 
keywortls, etc.) that can easily l>e dispensed with, LikewLse, 
Adobe tends to inseit long /II) tihjects (containing a kind of 
"digital fingerprint" for identification of the file) in PDF files; 
these aren't sirktiy neetleti. 

If yt^u keep removing superfluous objects and data items 
from a PDF file* you may lx* amazed at liow much ‘‘clata" you 
can actually get rid of without making Reader ctHiiplain. A 
careful re-reading of the PDF Sjxcification usually reveals that 
items you thottghi were mandatory aa" actually opiional. Kven 
the all-importnni 'xreP table isn't strictly needetl since Acrobat 
Ke;tder lan (and will, and doc^s) generate the ixres.siiiy h)ie 
offsets itself* at mntime. if the table is defective oi' mi.ssing. 

In late IW)* I spt)ast>red a contest at <www.aaoforTTiicom> in 
which the goal was to pn kIlkc the smallest [)ossil>le PDF File tliat 
wrote “Hello WlirkF to the screen without milking Aciohai Rc^icUt 
generate any eiTor dialogs, Amazingly, the winner of iliat contest 
.submitted a file lhal was <mly a little mure liian 2t)t) liytc^ long: 

%FDFF 

J 0 0 bj<</PagBS 1 0 i0> 

2 0 obj<</Kidst<</Parent 2 a 

tt/Rp*;nvircp^;«/Font«/R 

«/SiJbty pfl/Ty pel / BafieFont /Arl al >> 

»»/Conr<>nrs<<»st ream 
BT/R 14 

Ti (Hello WorldllTj 

endStream 

>>]>> 

trailer«/R<iot 1 0 R» 

Nt>Te that the second object (.Stirling with “2 0 obj,..”) is 
extra-long* w'iili many nested “dictionary” entries, ending cmly 
just before the word “trailer" at the bottom of the file. 11iis 
particular PDF tile uses 14-poinr Arial a.s the typeface. No font 
encodings are CEnheddeti in the file, liowever, Ixcause Arial is 


one of the base-14 fonts tliLit Acrobat Reader ships wiifi. (Arial 
replaced Helvetit^a in the vcfsion-1.0 releiLsc of Reader.) Every' 
Enachine UiaL has Acrobat Reader Is gtiaranieed to have Arial. 

There are many things technically "wrong" with ihis short 
PDF' file* incUtcling the fact that it has no xu-T table and contains 
a text stream dial is ofx.med with 'BT (lor Begin Text) but is 
never dosed w'iih TT' (End lext). In many ways, it;s a wonder 
Header can even parse and display this file. V’ei it docs. 

There Ls one small lechnical difficulty with this tile that 
impacis viewing: Namely, no posiiUmm^ lujhmmikm is given 
for the text — which means (since Reader "zeroes out" the 
current tran.sformaiion matrix, ov CTM* before displaying any 
block of lexl) dial the staging “pen position" for displaying 
“Hello World!" In this instance is ihe origin of user space: i.e., 
the lower left corner of tlie page. You have to scrolJ dowm to 
ihe very iHittoni of llie page to see the single line of text. To 
Fix this requires diat we add a transformation matrix of our 
ow n to the text stream: 

TIPDF ' i. 

1 0 Obj«/Pages 2 0 R» 

3 0 obj«/Kids[«/Parent 2 0 
R/Resources<(/Foiil:<^/R 
«/Subt.yp£?/Typel / BaspFont/Ariiil)) 

>>>>/Content)sLrcaitt 
BT/R 14 

1 0 0 1 72 7Z0 Tm 
TftMeilo World!)Tj 
endstream 
»1» 

LtoiU'tC</RotJl I 0 R>> 

C".;in you spot the change? We've added a line that ends with 
"Fm' (die tran-sfonii-matiix ojxrator). I'he six-numlxT matrix will 
\wk familiar to you if you’ve studied Postscript. 'Fhe first four 
luinilx'rs are .scaling and skew ing factors (signifying no change in 
ihost^ cham(ieri.stk>i, in ihis case); the luial two nuniliers are 
iransiatitJTi vafues in *x' anti y', resjm1i\ ely. Since tlie default user 
space in PDF has 72 units to the inch, using values of 72 and 720 
result in ihe .siantng )Xisition for our lexl results in tnir text lx;ing 
drawn t>ne inch bom the left edge of the page and ten inches up 
from the btJttom. (In PDF, y' units get bigger as you go itfx) Now 
our hqx>inE text will Ik^ dniwn wliere the user can sex* It. 

In the Perl script that follows, w'e're going to use* a variation 
of the foregoing PDF file as ihe basis (the lemplale,” if you will) 
for our dynamically genenilctl !M>F p:ige. While some experts 
may cringe at tlie tliouglii t>f using a 'liiiiken" PDF file as the 
sianirig fioint lor this kind of exercise, the fact is ihai for 
ilki.siTaiive purposes, a "sulxuomk " template file iif this kind is 
hard to [xrat. Besides, the prtxjf of the pudding is that Acrobat 
Reader doc-sn’i in any way “choke" tm the end re.sult. Wliat the 
user sees in his (or her) browstT is a fully functiona! PDF llle: 
one that can Ixf saved to disk (using the )>row'scrs S;ive A.s 
feature*) for later use. 

1'be CoMMtiN Gateway 

Colleaing infonnauon from Lisers is a common task in rlie 
wtjrld of die Web, calling for the use of intentetive forms. 
Sometimes* the fonn in que.stlon is a sialic IFIML Ole stored on 
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li sL-rv'cr^ but increiLsinglyj forms ihcmsclves ure 

dynamicjlly f^t'nenued at the .st.‘rvcr in rcsfKiase to user rec|uests. 
That is, the Ibrm iiself doesn't exist until a CGI script, often 
written in herl, generates it. 

CGI filie Common Gateway Interface) is mHliing iiK)i’e than 
u set of conventions for ()ushing and pulling informaTi(»n acrtj.ss 
an IflTl* eonneetion. hoijtis, and tlie scripts that retrieve 
information from web fomis, use the CGI prottxxjl to get the job 
done. Learning to write CGI scripts in Perl Ls an art unto itself, 
hut the joli is made ireinendt>usly easier if yon take advantage 
of some of the excellent Iree Perl libraries available for 
implementing CGI processes. 

Aigiiably the lx.*sl Perl librar>^ for this task is linarin Stein's 
powcriUl CGI.pni jxtekage. ‘HTis set of loutines (which lakes the 
[)ain cjut of writing HTML at the .server and dealing wath web fbmis) 
Ls St) usehil that it now ships with Peri as part of the Tull instalP of 
the language, Wutt liib means Ls tliat any Unix server that kis Peri 
paiddevel 7 or liigher (tts almost all do) aumnxttically has 
CCILpm, w^aiting to be tailed from any Perl setipt. 

When you use CGl.pm, you don’t have to worry alxuit 
whether incoming form data is l>eing supplied via GhT or POSi; 
wiiere iCs Ixdng storetJ on the ^'r^^cr, or any of the misty parsing 
details involved in cxlracting urlenaxled data from HITl^ 
streatTis, To get the value of a form Heltl called TIserName'’ from 
a Peri .script at nintime using CGl.pm, all you have to do Is: 

Sname " paraint‘tJaarName*); 

Here, $name refers to the kx'^il scalar variable imti wiiich 
we wish to srortf the value from **LfserName7 If the user has 
ryptxl T^jhn SmiilC into tlie relevant form field IxTore Submiiting 
ilie form data to the server, then $name will contain "John Smitir 
after lliis line of code exet^uies. Tlie jiaraniO function in CGLpm 
takes (*are of finding die incoming data, deerxiing it if ii\s 
urlencoded, etc. 

Dynamic Forms Using CGLpm 

One task CGl.pm excels at is generating HTML code 
dynamically. For example, to cTeate the HT.ML form shown in 
Figure 1, all we have i[> do is execute the following few 
lines of Peri: 

print lioadpr* 

statOiinilE Litle’>'PDF Bounceback, by Kas Thanias', 
b^col * ilFFFFFF') ^ 

pth2(^PDF Text t-ntry*)); 

print start_form, 

text a r ea (Users Text", 

-ro¥?t->2^i, 

Colinnnfj"> 60 ) 

subial t ( naiti(j”> * ac t i on'»■ vaJ. iie“> * Oen erat e PDF *); 

end_t'orm: 



Figure, L A form cn^ateei dyrmmkally CCLpm. 


Tlic function hit ^content here') applies an HTML Ieveb2 
heatllme tag arotind the text “content here"'; likewise, jM ) applies 
panigraph Utgs around a block of text, and so forth. Nesting the 
lUnclion calls causes the relevant ITTMI. tags u> nest corrcxlly* A 
common idiom in Perl tbr gelling miilli[>le strings to print to an 
fHitput stream is to separate the strings witli commas and put 
tliem l)clwcen pnnl at the start and a .semicolt)n at l!ie end. 
Functions like headerO, siari_form(), and cridJbrmO are pun of 
the CGLpm package, (In Perl, parentheses after a hinclif>n name 
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do nt)i amsiiliittf ft i’unction call operator." They are rherefore 
optional if no arHuinenis are given.) 

If you write a Perl script containing tlie foregoing lines of 
code, name the script “Fonn.pl", and place it in the “cgid'Jtn” 
direccoiy of your web server, then w^lienever anyljody goes to 
the scTipi’s URL, the stTipL will launch automatiolly and write 
the form show?n in Figure 1 to the caller's firow-st^r. "Utis Ls how^ 
many (if ntn most) dynamic forms work. 


A Dyn^vmic pdf Script 

At this point, believe it or not, weTe in a position to put 
together a full, working Perl script for producing an HTML form 
dynamically, retrieving the contents of that tfllled-out) form, and 
auto-gcneniting a PDF reply back to the user's bn>wser Listing 
I shows such a script, complete. 


Listing 1: dPDF.pl 

myipi 

A c«>mpk'tr t\rr1 iicri]>i fur :in HTML ftirm, rpirkn iog the 

furai's contemn. iUKl wriUni* the irontttiLs hack tnit as a PDF Be. 

#! /usr/bin/perl 


# Scripti dPDF.pl (tsimplc script to output PDF dynairslcally) 
(f © 7.000 by Kus Thuinus. Updates at wvw.acroforinG.cuin. 

If —-- 

use Ctn qy/:standard/i 

# Check purHm-s.anU if nuJI.stiow hirm..* 

OrayFontiO iitilesfs paramD; 

SallTe^l - paruB(( ’ UsersText'); 

print header F*appllcatlan/ pdf'); # ourpui PDF licattLT 

Send_PDF_Leadpr0; 

fnreach $linc {&plh /\u/.$aiiTexi) I 

print ■(* . Slinc . HTj*; 
print "\n“i 

print # gmo start uf next line 

print 

I 

Send^PDFjrrailerO: 

# - “ - - DrayFortnH - - 

sub BtawForiii t 

print header. 

Ktari JiI jjil ( tit;le^>"P0F Bounceback. by Kas Tliomaij', 
’bgcolor“>^#FFFFFF’). 

ptk2(font{I’Color")‘ted'],'PDF Text Enlry*))3: 

print start Terra, 

textareaC name^) 'IlflersTexi', 

* rnwr.^>24* 
columris”>60, 
wrap")virtual),p* 

submitHnaaie-^)*action'. • value")'Generate PDF’): 
etidTorra: 

exit: 

I 

If . - , - , Sund.PDF Leader0 . . . _ _ 

sub Scndl_Pi)F_beader t 

print «PDF LEADER: 

%PDF-1. 

1 0 obj«/Paans 7. 0 R» 

2 0 obJ«/KldGl«/Farent 2 0 R/ResourceE<C/Font<C/R 


Ct>OK!F5 IN PDF? 

With hyperlinks, styled lexi, form widgets, and 
Jitv^Scnpt all finding dieir way into more and more PDF 
pages these days, it w^ould appear that PDF page.s are (m 
theory, at least) capable of emulating a surprising number 
of features found in lil'ML web pages. Bus W'hat about 
storing cookies? Can PDF do that? Not technically. But a 
little-appreciated feature of PDF's JavaScript faciliD' lets you 
put persistent data on a user's mat:hine for later retrieval 
(unbeknowo.st to the user)^whicli is. of course, the kisis 
for most of the behavior associated wuth ‘^cookies," 

PDF's Javafscript binding allow.s users of Acrobat (the 
full commercial product; not Reader) i:o attach scripts to 
button events, page-open actions, and varioiLs other 
^trigger points" in a PDF df>c:ument. Among the built-in 
classes existing in Adobe’s Acrobat extensions to core 
JavaScript Ls a Global object class. One of the inetfiods of 
this class is called sctPcrsi5itcnt(). Applying this method to 
a global variable makes die value .st(.)red in that variable 
t>ersisient across Acrobat or Reader sessions. The way it 
works is that Acrobat or Reader will, upon encountering a 
variable that has been made persistent, write that variable 
out U) disk on program shutdown. (Conversely, it reads 
such variables from disk on launch.) The pcrsi,sicnt data are 
written to a file in the Plug-Ins hierarchy called giob.js. 

What is little-appreciated is the fact that even Acrobat 
Reader (wiiich is supposedly a read-onty program) can 
wTite a glob.js file to disk—and will do so, if u file contains 
persistent data created in JavaScript. Let's say you want la 
.store the string value “April 3(L 2{)()0'' persistently for later 
retrieval (po.ssib!y from a different PDF file akogether). You 
could attach the following bit of JavaScript to a Page Open 
action in your FDI' file: 

/ATcaic a global pro|3erty. my'String, oiid give H a v-aluc: 
gJobaLiiiyString = "April 2000": 

If make a pendst; 

global .setPetsiyteQt(“rayStriTig"): 

When these two lines exectute, it telLs Reader (or Acrobat) 
that the value in ‘’jiiyString" needs lo he stored to disk, in the 
globjs file, at program shutdown, Liter, anollier I’DF fib an 
execute JavaScript containing the following: 

// creaff a bUiik string: 

var lastSesfiiotiDatg = new EEririgOj 
// rtttricvx'*myString' 

it (typeof (global.rayString) 'undefined') 
lastSes^ioiiData ■ global .raySt ring: 

■Ihe (local) vartible lastScsKiunData will now contain 
"April 30, 2000." 

If you’re ever curious a.s to wlial’.s in your g!ub.is file, just 
look for it on disk (with Sherlock) and open it in SimplcTcxt. 
It’s a plain ASCII Rle. 

Yum.~Kas Thomas BQ 
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So Fast! 


Peered If 

OpinSise SOI 


«/?!ijhtyp6/Typel/BaseJQnt7Ariai>> 

>> >>/Ccjntentf:< <>> stream 
H1V R l/t 

i 0 0 1 n 700 Tm 
n Tu 
TfOTj 
^DF.LEADER 
] 

^ - --Send PDF Trail er() 

suit Sci(d_PDF_TraIler I 

print «PDF_TKA1LER; 

endatrean 

»]» 

Traller«/R£>ot 1 0 R» 

PDF_TRATLER 

I 


After a use direc tive to nuikc sure l*erl knows we neetl to 
use tlic CGI.fjjii package, we check to see whether the CGI. pm 
runction paramO returns nothing, In w'hk'ti ease it means tlie 
scTipt ts being allied for the firsi lime. If ilie seri[>t is Ixing called 
for the firsi LiiiiL\ it means we need to generate the HTML form 
of Figure 1 — which is accomplLshed by the subroutine 
l>rawForni(). Otherwise, if panmiO is ncjt nil, we're responding 
to a hit on the “Generate PDF" button <w^hich is the form's 
equivalent of a Submit button), 

If we're responding to a lui on the Generate PDF button, 
the first order <jf [>usiness is to retrieve the user-entered text, 
wliich wc do wiih: 

SallTr^xT “ param(*User£Text’J: 


The texi^rea field of the HTML form is named “Users text"; 
hence, we want to retrieve whatever the iLser typed ihcrc. The 
foregoing line of crxle captures rhe user's text into a single big 
string (a solar variable, in Perl parlance) called SallText. We ll 
have CKiaasion to parse that big string into smaller consiiiuenis 
{rc[iresenting mdividual /nies of text) in a moment, 

Before we am write PDF lo ilie user's browser, we liave to 
open an UllV conneetiori and send an ITTIP header with the 
approf>riate MIMF type for PDF (which is “application/fKir). 
1'his is the browser's way of knowing wliai kind of file is about 
to arrive. The browser can take a]ii>ropriate action in terms of 
lattnehing helper apps, handing off control to plugdn.s, or 
handling the tmnsaction itself. In this instance, if the user has the 
Acrobat browser plugdn insiallcd, the browser will hand control 
to the p!ug“in. It’s also jx>ssible that the user has set the browser 
up such that incoming PDF files are redirected to I he standalone 
Acroiiai Reader app. [f ilic MIMF type* “api>licatkni/pdr has not 
Ix^en registered witli Lite bR)wser, the browser wtl! react lo the 
incoming header by asking the user w^hat to do with Uie aSxmt- 
to-arrive unknown file type. Tlie user can then cancel out of the 
tran.sacfion, .store tlic incoming file to disk, etc, 

OjKming the I DTP cemneaion and sending the proper 
header is done with; 

print header ("application/pdf **): 

After that, our script goes to a subroutine called 
SencLI^DFJejiderO^ This subroutine simply writes 200 bytes f>r so 
of raw PDF to die PFTTP cxHinection. Mast of that axle sliould liK>k 
familiar to you from our disai.s.sion of minimal PDF filc-s aariier. 
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Writing ■iii£ User’s Text 

Ncxr (omtrs our script's ""nuiin UK>p," you iingfu siiy, in 
which wc parse llie user's text into individual lines and write 
liiern out as PDF text-sucant daUL We ust* splitO function 
lo divide the $al] Text string into substrings, spliiiing ai every 
newline. Then w^e write a line of user text» in [>arentheses, 
followed by the Tf oi)erator (PDF's ‘"writeline” operator), and 
after every line of text sej pnx'e.ssed, w^e write a 'T*', which (in 
PDF) means lo drop clown lo the start of the next line (using the 
current leading) and prepare the virttial pen to write more text. 

After writing eveiy line of user text, we call 
Scnd^PDFJTrailerO lo write out the last few bytes of our PDF 
template. At that fxiint, w'cTe llnished. 

An example of a dynamically generated PDF page u.sing this 
script is shown in Figure 2. 



Fijiure, 2. A j^cticmk'd PDFfife. 


The Gri;at Escape 

At this pt>inc we have a .script that olxxlienriy writes tjur user's 
text input as i4-t>oint .Anal, tn black ink on a white PDF page. Not 
veay inreresdng-lfMiking. It would lx nice if wc‘ ccniki ja7.z things 
up a hit by cimvving our text in o>inr, fxrliaps in various addiiional 
sizes, it would also lx nice if we I'otikl specify stHiieilting other 
than a pure wdiite Ixickgrmind. liui Ixfore we pnxeed tf> increase 
the spiff fatior of our PDl’ we need to attend lo i>ne small detail. 

l^DF represents strings initrnally ;ls ASC’II character siectuence>s 
iaside [tarenilieses. TluJ-s* whenever a siring contains parentheses as 
pan of the text, they neetl to lx ^’scujxd" with a parceling 
backslash. Otherwise, the PDF^ interpreter, u|ion encountering a 
right‘paienthesis inside a bkxk of lexu may think the text string lias 
Ixxn ttrmiruited! 'llie right-paaii w ill lx treated as an entl-of-string 
nuirkcr. TIiLs t:ouki lead tn stmnge errors if our trscr is in the habit 
(as many of us arc) of loa<ling up text witft parentlieticaI aamtrks. 

f-oiTunately, it's not hard to inip parens and "esc^ijx thenr 
aulontaiically for tlie u.sct. Of axise. w'e alsii have lo imp and 
esc-aix /mckslaskfs in ihe user's text, Ixcause (again) PDF trails all 
backslashes a,s "special" in a tt.‘xl stream. 'Vo deal with parens and 
Ixickslashes, wx declare an asstxiaiive array in Perl as inllow^s: 

\ \ ■ -> • \ \ \ \ v, 

=> -M** 

*(* “> *\C): 


llie way this special kind of array (s(7metimes called a hmh) 
works Is that when we want to kx>k uf) llie replacemeni” for, 
say, a liare right-paren, w'e just need to do: 

Note the dollar sign preceding the Imsli name (and the curly 
braces enclosing die array index). In Perl, tlie dollar sign means 
we are cixrcing the array liKikup into a scalar amtexl. When the 
above statement ev'aiuates, ii will evaluate to llie lookup value 
‘\)* (i.e., the string representing our properly csca|xd paren). 

Of course, Perl (like PDF) cdso treats Ixtckslashes as s|xdid, 
whit'h means ilnit ;i string repiCTicnting a literal back.skish neecLs to 
lx escaped — with a backslash! 'fliat is, the string 'W |>rints as one 
backslaslt (not two) in Perl. likt*wLsc, '\\\\/ i.s treated as two literal 
Ivackslashes in a row, not four. ITiat's why the firsi kxikup item in 
our hash, namely '\\\\', is asstxiated witli '\\\ (Omfu.sed yet?) 

Nttw. We need lo check every line of user input Ixfore 
writing it as raw PDF, .s(j that any paren.s or backslashes 
< t>ntained in the user's text get converted U> their properly 
escaped effuivalents, preventing AaT>bat Header from choking. 
We can accomplish this essential check with ihe following line 
of axle, inserted in our "main kxjp": 

$line -- s/([\\()l)/$PDF ESCAPES[$11 

“Wow,” you're profxibly muttering, ‘'what a wetrd-lcKiking 
line of cotie!” And indeed it is. A Ped fan will recognize il 
immediately as a pntverful ri\^cx4)£iscdsuhstiiuP^^^ Ixing 

shoit for ‘Tegular ex[ire.sskjiT). In Perl, a statement like 

SmyString n/thlu/tlutt/i^r 

means to .scan the conienis of SmyString, l(K>king for die 
substring 'this, and trfxm llntling a match, snbsiifute (per die 
leading lowxrcase 'si the .string ihat'; and oh, by the way, do 
this re/H^atedly (glt>b;illy) dtroughout the entire contents t)f 
.$nTyString. (Tliai's what die irailing lowercase ‘g’ means.) 

in our somewhat compliaiied sul»s1itullon tiperaiion, we'm 
sranning for any march of the regular expres,sion IWOf which Is a 
c/?r/mc7er dass wiiti llm-e memlx^rs: the backslash character 
(winch we have to escajx with a Ixickslash, ff>r Perl’s benefit; 
hence A\'), the left-paren, and the right-parai. St|uam lirackets 
mean tltal these char4Klers form a cla.s.s of allowable “march” 
characters. Any niatcli of any one of diest^ chamtlcrs (in any order) 
inside llie target string will trigger a iiiu" Rnclosing the entire 
cliaraaer ckuss tdihiii l>cnvikhL^i% as in t|\\()l), tiieaiis we want 
IVrl to .stone a icmlxmiy ay/y of any nniich that <xxtits, in a 
variable called $h (If you'iv mx fainiiiar widi ihLs idiom, ebn’t 
sfxntl lcx> much time W'orrying alxjuE it riglit now. You can always 
axid up on regexes hilerj Oiir a^placcment value, which Peri 
consults whenever a "hit” liappens, in this case is 
$PDF_HSCAPt!SI$]| — dial is to say, we use die niaicli value ($1) 
as an index into our a.sMxiative array, in oixler to retrieve the 
ap[>ro[niate a'placemenl .string. This trick will only work, however, 
if we rememixr to [lui a tniiling k>weR:tuse ‘e' on the end of the 
expression, w^hk+i me;ins etxifiuife rhe nplacemetii as a Peri 
e^resstort. Otherw i.se, Perl will literally sulisiiEuie whatever'^ in the 
replacement |X)sition, unevalualed, Tliat’s not w'liat we want 
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Upping niE Spiff Factor 

An I started lo suy betbre, it would he nice if we could 
""spiff up” our PDF ouipui a InL augmenting tt with colored 
text, styled text, t)r pcrluips some vector graphics or different 
background colors, etc. “ anything except plain old black 
text on a w'hite background 

Adding extra spiff turns out to be astonishingly easy. All we 
need to do is let the user “"drop down” into low-level PDF 
whenever he or she w;in!.s to. Fol|{>w me for a minuie. SuplXKH* 
we invent a special “escape command" of our own, signified l>y 
(let’s say) the ASCII string <@>. Well cill this the “escape-to- 
PDF" operator. To get back to normal Lext-writing mode, we ll 
rcx]uire the use of </@>, which well call the “escape-to-text" 
ojXTator. Anything bracketed by <@> and </©> gets treated as 
raw' PDF. While your user is in “raw' PDF" motle, he can make 
use of any of the PostscTipt-likc page operators and vecior* 
draw'ing comma ntLs recognized by the PDF SptxafiraLit>n: m for 
iiioveto, I h)r lineto, rg for setting the RGH color, Tin for set 
matrix, B for fill and stroke path, etc. (See die till given earlier 
for the fomial PDF Spet:ific'atii>n, at Adobe's web sited 

Using the same regex-based substituiion trick ttial we used 
before, we catt add one more l(K>kup table (or assexiative array) 
tt> cjur script, and :id(l one Tnorc regex-substitution tine to our 
main loop. Only this lime, the hash will return a value of ")Tj ‘ 
for any hit on <@>, and a value of * for any hit on </@>. That 
w'uy, whenever the user ty'pes <#> os pan of his text stream, our 
script fiutputs a PDF end-of-string marker, followed by the I’DF 
"write line'' operator (Tj), sp(K)ting Acrobat Reader into letting 
the ii,ser write niw page openitors, if he wants to. When die user 
t>';xrs </@>, the scTipt cmtiiuLs a “liegin string" marker, and 
Reader Is sp<K)fed into going f>ack into text-stream mode. 

What Can You Do With It? 

Now weVe got (juite a bit of jX>w^er incur li^mcLs. If you know 
a little bit of PDF, you can eremite almost any kind of display magic 
you W'aiK widi your dynamkt'ally generated PDF dtK'ument, let's 
try tile lollow'ing ctxle entered into our fomVs rmiin text area: 

<@>0,85 0,65 0,65 RG</@> 

(@>1 J 110 V 350 600 m 250 600 1 a(/@> 

<#>,6 .6 .6 RG</f> 

<@>18 w 72 72 m 72 720 1 540 720 1 540 72 1 fl</e> 

<t>0 1 t 0 144 520 

Let*a try Hotac? rotated text. 


'fhe end result is .shown in Figure WeVe created a PDF 
tUx'ument containing a large grey Ixix (going around Uie edges 
of llie [lage), a filed grey circle, and the words “IjeFs try some 
rotated text" rvtnning vertically up die page. 



Figure .i Ciistom-genemtad PDF amlaining rotated text and 
stroked iM/Uor graphics. 

To understand w lull's going on, let's lcx>k at the alxjve fonn 
input, one line' at a time, 'I'he first five lines are encapsulated by 
<@> and </@> , which means we\v writing raw' PDF'. Hhe first line 
of raw' PDF a>ntains 0,85 0.8S 0.85 RG, wliich sets the .stn>ke color 
(in our default RGB color s[>ace) to 15% grey, lo PDF. RGli duinne! 
values run from zem to 1.0, with 1,0 ! icing brightest, 'llieiefore, 
setting each cluinnel to 0,85 makes lor 15% grey (or 85% white). 

■n>e sea)nd line Ls more compHaited. Iksically, it says to set tlie 
default line cnd<ap style to rounded endeaps (diat’,H what *1 J’ 
iiieaas); ,set the default line width to 110 pixels (thas '110 wO; move 
the fx^n to pttge <xx)rdinaijcs of 250,()00 <"m' merin.s "moveto”); draw 
a line to 250,600; and finally, .stroke tlie path CBM. In plain English: 
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“Draw a 7x:^rt>-length line, 110 ]:iixels wide, at 2'50,600 w'ifh immded 
end aipsr Since the line has zen> km^nh, oniy ihe end an' 
dmmi In tills way, we sp(X)]' AltoIxh into drawing a j^erfea dale, 
whidi kx)ks Qlled (ultlurngli anally it's oniy stroked), lliis is an old 
Postsc'ript hack for draw'ing hlled ciaics. 71ie reason we itse ii hea^ 
is ihat PDF doesn'l have a “draw' dnde" operator, just Bczier-curvc 
ojx.Tau>rs. (1 dont know' alx>iit you, but I Kind the ideii of drawing 
a drcle itsing linked Bezier segments too painJiil to think about.) 
Next, in the ihirtl line of raw^ l^DF, we set tlie suokc color to 
ga:y (6{yM> wliiie) wiili ,6 .6 ,6 RG. 

In line four, we change the default stroke width to 18 pixels 
<'18 w’)] move the pen to 72,72; draw a line to 72,720; another 
line to 540,720; a line to 540,72; and then we use the 's’ 
command, which in PDF means "dose this path and stroke it,” 
This is how' wc pnxluced a thick, clark-grey line going around 
the margins of the page. 

Finally, in the Fifth line w^e perform some matrix magic. 
Iransform matrices, in PDF (as in Postscript) consi.sl of six 
numbeoi, the first ftnir of wliidi sptxify scaling and rotation. To 
rotate die c<x>rdinaie systeiii, just make sure the first four 
numbers represent (ccmsecutively) tlie cosine, sine, negated sine, 
and cosine of the desiaxl angle, fn tmr example, we used 90 
degrees as die angle (hence die matrix values 0, 1, -1, and 0). 
The final two nunilxrs in die transform matrix represent 
translation values in arand y. ‘Ihai is, we move the origin of space 
to whatever diese nutniicrs are (in diis case, 144,520). Recall that 
the origin starts life at the kmer lel't corner of the page. 

Now when our text is drawn, it begins at 144,520 but 
runs at 90 degrees up the page. Since text is (by derault) 
filled hut not stroked, it gets drawm in black (the default fill 
color, which we have not changed). 

Simple as pi. 

CONCtUSlON 

We’ve covered an incredible amoimt of ground in a 
relatively small space. Not only have we siiown how to serve 
dynamic PDF pages from a compact (80 lines or so) Perl script, 
but w^eVe integrated a low-level “mw PDF” erlitor intt) the data- 
inpui Form such that if the u,ser w'anus to, he can produce 
sophisLicatetl grajdiics effects inside the genemted PDF* page, (A 
iive” copy of tliis script, and others similar to it, ran be found 
online at lirTp://www,acr(>ft>rms,c(>m/dynamicPDF,lUfiil,) 

Of c'OLirse, many useful additions could still be made to our 
little scTipt, A useful exercise would he to add such features as: 

• Additional fonLs, and a facility for the user to clxmge font 
sizes on tlie fly, 

• Automatic line-w^rapping, with or without justification, 

• Cusiom margin widtlis, 

• Custom Ixickgiound colt>is. (Tlib is just a matter of drawing a 
filled, colored rectangle Luge enough to awer tlie entire pjige.) 

• Stylesheets. 
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assemble commands 
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EXPERIENCED WITH APPLESCRIPT? 

• Unmatched single-step interactive debugging 

• Watch and modify global and local variables 
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You can probably think of lots of other features that would 
be nice to have, 41ie gof>d new^s is, now ytiuVe in a position to 
implement them, liccause (as you now know) dynamic PDF 
really isn't that hard, IQ 
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QUICKTIME 

TOOLKIT 


By Tim Monroe 


Opening The Toolbox 


Controlling QuickTime 
Movies With the Movie 
Toolbox 


iHiRODvcmm 

In Ihf previous iwu QtfkkTime 
loalkil ti n ides, we‘ve incused tilniosi 
exclusively on playing QuickTime movies 
using mi jvie control lei>i. This is by hir tlie 
easiest way to intinage movies and lo 
sLipfvon I he sinntiaril lypes ol' user 
inieraction with movies, Indeetl, some 
ty|X^s of Quiek'riine movies canriol he 
presen led lo or managed hy the user 
wiihouL a movie c’onirolleiv hut there are 
other types of Quidd'ime movies (hkjsI 
nottihly, standtird linear movies) that can 
lx.‘ played hack wiihotii using a movie 
conlrollcT, In this aitide, weT see how lo 
acetmtpILsh this. In effect, ourgi)al will he 
lo provitie all the capahiliiies that are 
provided ljy our basic a[)plicaiic>n QTShdl 
— for linear movies at least — but without 
the assistance of movie controllers. Well 
show how to Sian and .slo|-) movies, 
pjfwide basic editing vServ'ices, and .scl 
varir)us l(K)ping states. 

Wiiy 11 light we warn to do this? Well 
there are silLiations where you want lo 
play Quickrime movies iiut don't 
necessarily want the user to Ix^ able to 
mani|)ulale tliose movies in the ways 
typically afforded hy movie controllers. 
Perhaps the simplest example of this is 


found c|uitc often in gaine.s, where you might play whafs called 
a ail movie or a ail seme w hen the user conipleles one level 
and advances to the next. The cut movie sen'e.s as a transition 
from one level to ihe next, and you generally don't want the user 
interrupting or (lieiiven fesrbid!) editing your cut movie. So using 
tile full-lledged movie controller interface is ilefinitely not tlie 
he,st way to handle Quick'l ime movie playback here. 

There are also more compiicated examples of using 
controller-less QuickTime movies. For instance, you might want 
to use a linear (^)uickTime movie as a texture for a 5D object 
that's being displayed hy your application. Figui-e 1 shows a 
window of tlie application TexuireHyes, witich uses QuickDraw 
31) to define and render tiiree-dimensional ohjecTs. In this 
window^ we've createtl a culx^ anti set its surface texture to be a 
QuickTime movie. 



figure L A QitkkTinie movie used m a lexlitre on a 3D ohjecL 

Similarly, we might warn lo emhcfl a QuickTime imwie 
within aiK>ther QuickTime movie. I'or instance, QuickTime VK 
allows us to drasv into a pant>iamie node. We can use this 
capalriliiy to draw the indtvidnal frames of a Quic kTime movie 
into a panorama, as shown in Figure 2. Here, tlje toy train on 


Tim Monroe <UHJiircx'ii^applcccom> is a sofiwaiX' engineer on Apple's Quick Time team. Me is currenily developing sample 
ccxle and utilities for the QuickTime software development kit. 
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tix" table isn't pail cjI the original panorajiia. Raihcr, wcVc 
drawing the frames of a standard QuickTiine movie (one of 
I hose fnimes in shtavn in figure 3! into the panorama, using the 
Quick'I'iine VR afiidicaiion programming inlerfacais and some 
QuiekDraw routines to droj> out the !)Iack l)ackgroun<-L The net 
eftecr is tliar the train appears to travel in a eircle fin die table^ 
thereby imparling some motion ami sound to the olhenvise 
static and silent panorama. 



f 2. A Qj/ki^'/hne UUo ^ 

Qi/kk7}nic' I7f paftomma. 



/*igHtTe S 7bL^ Q/uck/kfie moiie /;/ J. 

We might also want to embed a linear QuiekTiine movie 
into another lineal' QuickT ime movie, as shown in Figure 4. 



Figure 4 A QukkTm/e mone emh^dc/ec/ 
mjo (4 QuicFfime moiw. 


The ptiini is not that we eoiikliVt have used movie eoniiollers 
lo help iLs display anti manage fhe on scenes or the texmred or 
emlwlded QuickTime movies in tiiese* stirts of rases, leather, ilie 
jioini is that we don i neet! to do so. In the examples we ve 
inendontxl. we just need a way t<j manage the display of the mtivie 
frames at the appropiiate time (and tt) play back the movie s sound 
tnick, if it lias one). So in those cases the cJiily seivices we really 
need are QuickTime’s imaging, sountl producing, and liming 
servaces. We doril need the n>busl user interacl ion serv ices 
piovidevl by the standard linear movie contjollei; 

It's really a question of levels: the movie controller interface 
for conU'olling movies is a higlier-Jevef interface Ilian what w'e 
need to accvjmplisli the tasks oullined above. Now w'c'll drop 
tiown a level and diiectly use the seivices of that part of 
Qiiicki iine known as the Momc T(}(^!lx>x. Tht^ Mfivie Toolliox l.s 
really the licail and soul of QuickTime. It pnn idcs sta-vices for 
opening movie files and extracting movies from them, inlaying 
movies, editing movies, creating movies, and much more. 
Indeed, the original bisick Macinfosb diK'unicntmion for the 
Movie ‘Ibolhox (that i.s, circa 1993) lun to well over 400 printed 
pages. To a targe degree, programming with QKiick rime is using 
the jMovie T(x>lbox, 

So here's what w^e want to accoinfilish in this article: we 
wxmt to modify tnir basic application Q I’Nliell s<i that it can open 
and play back linear QuicTdIme movies without using movie 
controllej^. Let's call this new application QTMooWLoollxix, in 
honor of the tact that we ll he doing everything using the Movie 
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Toolbox. Since we Ye nol using a movie conirollcr, Lliere will be 
no movie controller bar in our movie windows. A typical movie 
window wall therefore look like the one In Figure 5^ 



Figure 5. A movie window displayed QTMooVfoolbox. 

As indicated above, we want to suppoit the standard 
movie editing capabilities, so our application s Edit menu will 
be unchanged (though of course ihe code providing the 
editing capabilities will change quite a bit). We also want to 
provide the user a way to start and stop the movie and to set 
normal and palindrome looping. Figure 6 shows the Test 
menu that we wani to support. 

ESI^_ 



Figure 6. The Test menu for QTMooX^oulhox. 

'I'he last menu item here ("‘Add Picture In Piaure..*") is 
particularly inicresiing. It allows us to eiribcd one linear 
QuickTime movie inside of another linear Quicklime movie (as 
shown in Figure 4), As we 11 see, it's fairly easy to use the Movie 
Toolbox to accomplish tius. 

Getting Started 
Setting Up to Use QuickTime 

before moving fonvard will) our QTMooVToolbox 
application, we need to liack up a step or two to fill in a few 
details that we skipped over in the first two articles. In order to 
use any of the QuickTime services, we need to rriake sure tliat 
the QuickTime client software is available on the target machine. 
On Windows computers, we can do this by trying to initialis^e 
the QuickTime Media liiyer, like this: 

myErr = initializeQlilL{OL}: 

If InttializeQTML completes successfully (that is, if myErr is noErr), 
then we know' tliat QuickTunc is available. On the otlier liand. 


if InitiaNzeQTML doesn't com})lete successfully, then either 
QuickTime of some other e.sseniial component is missing, in 
which case we will just exit the application (pcdiaps after 
infonning the user that QuickTime needs to lie installed). 

On Macintosh computers, we can call the Gestalt 
function to determine whether QuickTime is available, as 
s}K>wn in Listing 1: 

Listing 1; Determining whether QuickT ime Ls available. 

QTI ffilsJsQiiickTlmelnstalletl 

Boclean QTUtils_IsQuickTimeInstalled (void) 

\ 

long inyAttrs; 

OKErr myErr = noErr: 

myErr = Gestalr(gestalrQulckTlm^, ^myAttrs): 

return (rayErr = naErrh 

1 

On citliLT Windows or Macintosh computers, once we've 
determined that QuickTime is indeed available in the current 
openiting environment, we need ro call the EnterMovies font lion, 
like so: 

myErr ^ EnicrMoviest); 

EnterMovies initialize.s the Movie Tt3otlK>x, perfonuing any 
necessary set-up for our aiiplication (such as allocating any 
private .storage it might need tf> u.se on our behalf). As with 
InitialfzeQTML, we will check the value returned by EnterMovies 
and exit the application if an error occurs. 

When w'e are finished using Quicklime .services — usually, 
when our application is about to terminate — we should undo 
the %vork done by EnterMovies and (on Wind<jws) InitializeQTML, 
Wc can call Lite Exit Movies function to terminate our connection 
with the Movie Toolbox. On Windows, we also need to call 
TerminateQTML to iinregister our applitaiion from the 
QuickTime Media Layer. 

Using Application'Specific Data 

Suppose now lliaL our application is up and running, that 
we've successfully initialized QuickTime and the Movie Toollx)x, 
and that the user 1ms decided to (jpen a movie file (perhajis 
using the Open command in llie File menu). Our basic cross- 
platform framework calls the QTFrame^OpenMovielnWindow 
function to prompt the user for the movie file to open, cremate a 
window object record to hold basic informatkm about the movie 
and die file it is contained in, open a new window on die 
screen, adjust the size of that window to fit the movie(s natural 
size, and do some other useful set-up before ihe u.ser can l>egin 
to inicraci witli die movie. 

QTFrame^OpenMovielnWindow also calls the function 
QTApp_SetupWindowObject, defined in the file ComApplication.c, 
to allow our applic^ation to perform any a[)plication-specific 
actions on die new mtjvie, lx.Tore it is displayed to the user. Bc;>lh 
of our previous applications (namely, QTShell and 
QTController) have not put any code at all into 
QTApp_SetupWindowObject because die default configuration 
was .sufficient for our purposes dien. I lere, for Ql'MooV1oollx)x, 
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well need to change that, for two reasons, f’irst, we need to 
maintain .some information tor cacli open itiovie window 
iK'ytHid wliai is attained in the window object record. Second, 
since we are not nsitig movie controllers in the Q1 MooVroo]lx)x 
application, we need to do some atlditional work to prepare our 
movies for playhack. Let's tackle the first task here and defer the 
second until a bit later, in “Preparing JVIovies Por Playback”. 

We already have the appanitus in placaf to support adding 
application-specific data to our movie windows. As you may 
recall, the window^ objea tecord includes the field fAppData, 
which is declared to l^e of type Handle. We put this field there 
precisely tt} provitle ourselves a place to store any information 
tliat is specific to a particular af3plication (since we didn’t want 
to be changing the framework files all the time). For 
Q'rMooVroolbox, well define a siructure of type 
ApplicationDataRecord that contains tliree fields: 

LypcdcT struct ApplicationDataRecord I 

MovieEditState fMavieEdl L Slate://The edit stare of Itic movie 
Movie f F1 FMov 1 e: // the piensre-in-pictuif movie 

Re c t t PI PRec t; // i he pici LUf iii-pii: nirc tt'ctunglc 

I ApplicatianI)ataReccird> •AppIicationDataPtr. 
**ApplicationDataHdl: 

Wc don't need to explain these fields quite ye! (though the 
comments should give you a good enough idea of wlinr they are 
for). But we do need to show how^ the application data record 
gets created and attached to tlic windtm' object. We do tliis in 
the function QTApp_SetupWindowObject defined in Listing 2. 


Lontroller. We might as well just dispo.se of the controller, so 
we're sure it’s not doing any work for us. 

The second thing we do in QTApp_SetupWindowObject is 
cal! NewHandleClear to allocate an application data record 
and initialize its fields. (Of course, die initialization here is 
overkill, since NewHandteClear zeros the bytes in the newly- 
allocated blocks nonetheless, it's useful to make this 
initialization explicit.) Then we set the fAppData field of the 
window' object pas.sed to QTApp_SetupWindowObject to the 
newly-aI located han<lk\ This allows us, as wc intended, to 
kee[i a copy of tills record for each movie window-. 

The file ComFremework.c defines a couple of Fund inns 
that facilitate retrtevtng the applicatit)n-specific data attached 
to a movie. For instance, we can use the function 
QTFrame^GetAppDataFromWindowObject, defined in ii.sling 3, 
to retrieve the application-specific data asstniated with a 
window- object. 

listing 3: Getting the application-specific data attached to 

a window objecL _ 

Q'rFnim(;JictApp!)atarnjmMnO(JWObi«xt 

Handle QTFraiJie_CetApp3)ataFromWindowObjeci (WindowObjoct 
tbeWindowCibject) 

i 

// make Mire this is a, window object Ixlon^rinj^ m oitr^pplicittion 
J f { IQTFri3Tiifii_rsWlndcnrfObjectOurs (theWindowObject) } 
roturn(NULL): 

retundt*'theWlndowObjcct) .fAppDat.i); 

1 


Listing 2: Setting up a windt>w object, 

QTApp_SetupWind< > wObfeci 

void UTApp_SetupWitidowObject CWlrsduwObjiac L ibcWirKtoviObject) 

1 

Movie niyHovie = MULL: 

ApplicatioiiDataHdl myAppData = NULL: 

OSErr inyEcr = noErr; 

if (rbeWindowObJect 1- NULL) E 

// get rid of the mtmf cmtmlier that's alneath' attachai m this window ohjett 
// w'c do tliis to illustrate hK>w to manage m!>vj<^ without u^^ing a movie controller 
if ((*’theWindowObject).fController != NULL) [ 
HCSetActiouFiiterWithRetCon{{* HheWindowUbjeet) 

.tController, NULL* OL): 
DiEposeMovieController((**theWindowObject).fController): 

(**tbeWindowObject).fController = NULL: 

I 

// nlloc0rc an applicarion-spedfit: data rei^ofd 

myAppData = {Applit:atiorJUaL^lUdl)NewHondl^?ClG^t^ 
(glzeof (ApplicationOatiiRecord)) : 
[**tbeyindowObject).fAppData - (Handle)niyAppData; 
if (jtiyAppData f= HULL) ( 

[“layAppData).fHovieEdltState = NULL: 
(**royAppOat;^S.fPTPMovie = HULL: 

MacSotRcct(^( * ^inyAppDato) .fPTPReot. 0. G, 0. 0): 

] 

// some lines oaiiticd here 

1 

I 


Notice that the fir.st thing we do in 
QTApp_SetupWindowObject is get rid of the movie controller that 
has alrciidy liccn created by the time QTApp_SetupWindowObject 
is called. That’s because (as you already knowd we w^ant to 
illustrate how to manage movies without using a movie 
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Similarly, wc can u.se the function 
QTFrame GetAppDataFromWindow, defined in lasting 4, lo 
retrieve the application-specific data attached to a particular 
movie window. 

lasting 4: Getting the application-specific data attaclied to 
a movie window, 

Qll^ramcjCiciAppOaultimiWinaow 

Handle Q‘rFr4me_GetApp0ataFrontWindow {HiiwlowReference theWindaw) 

I 

WindovObject royVlndowObject = MtLL: 

ntyWindowObiect - QTFrarafi GetWindow0bjectFrfrtnW3ndow(thoWlndow]; 
if (myWlndowObJect “ NTITJ.) 
return (Nin*L): 

r e t u r n C QT F ni L A p pila t aF roniW i nd oi*?Ob j e C t {myWlnd OVO b J ec t)): 

) 

Well use these functions extensively tliroughoui ilic rest of 
this article. 

Updating the Application Framework 

The basic framework for playing QuickTime movies thiU 
we’ve used for the QTShel) and QTControlkT sample 
applications makes extensive use of movie controller 
componcnt.s to manage the movie playback and any user 
interaction with the movie. It use.s movie controllers to help set 
the window si/e, handle movie editing, pr<H esHS movie related 
events, and a handful of other important tasks. So, I must admit 
thai f w'as more than a little worried when I set about io 
develop the Q'l'MooVlboIlKSX application fm- this ankle. After 
all, the ver)^ first application-speciHc tiling we do (in listing 2) 
Is threw away the movie ct.min>llei ihat the fiamework so 
kinelly created and configured for us. l low^ much of the entire 
framework was dcjiendent upon W'ork done by that movie 
controller? On asked another way, how inucli of the basic 
QTSfiell framew'ork w'oiikl we need to rewrite in oriler to play 
back movies using only the Movie Toolbi>x? 

Surprisingly, very little had to change. In fuel only three 
functions ntxxied reworking to handle the new^ assumption lluit 
the m<.)vie window might no longer have a movie conljToller 
asstx'iated with it. Ini’s! of all, the QTFrame_SizeWindowToMov(e 
function originally contained these lines: 

myMC = (*‘tbeWlndowDbJect).fControiler; 
iityMovie {* *theWindowObJect) *fMovia: 

if (MCGetVlsibletmyMC)) 

HCGetControll^^rBoundfiRpcttmyMC. ^ttnyHovieBourids): 
else 

GetMovlc'floxttiyMcJvie, ^dyHovieflounds) : 

This just says: if ihe movie has a visible movie controller bar, 
then get the desired window’ size by calling 
MCGetControllerBoundsRect (which returns the rectangle ihai 
encloses the movie and the movie controller Ixir); otherwise, call 
GetMovieBox (which returns the rectangle that encloses jusi the 
mtjvie). To allow for the case where there is no movie controller 
at all, we can rewrite die key lines like tills: 

GetMovieBoxCinyMovle, SmyKovieBounds); 


if (nyMC [= NULL) 

if (HGGetVisible(iiiyllC)) 

BJCG^tCoRtrCfllerBtJUndf:Rt!Ct fsiyHC» imyHov leBounds); 

Second, tlic framework function 

QTFfame_HandleEditMenultem also assumed that every movie 
window had a movie controller associated with it, in which case 
it could use movie controller functions like MCCut and MCCopy 
to kindle the Edit menu items. In QTMtx>VToolhox, this is no 
longer true, .so we need to provide a way for an application la 
intercept llie Edit menu commands and do its own type of movie 
editing, We can do this very simply l)y insciting a call to 
QTApp_HandleMenu before QTFrame^HandleEditlVIenultem 
liandles tlie menu items. If QTApp_Han die Menu returns the value 
true to indicate that it lias liandled the menu item, then w'e just 
skip the rest of QTFram©_HandleEditMenult0m. We'll see later, in 
“Editing Movies", how our application actually handles the Edit 
menu items; for tlie moment, at least we have successfiilly 
provided a way to prevent tfie franicw'ork from try ing to liandle 
ihein using movie controller functions. 

The Iasi important change we need to make to our basic 
framework Is to provide U way for liolli our Macintosh and 
Window^s applicaiioas to tell the Movie Tik>I1x>x to play any 
movies that are open. When weTe using Qiiick'rime, we don't 
ju.si Stan a movie [ilaying and liien forget alxnii it^ expecting 
perhaps that it will pby through until the end and then .slop. 
Instead, From time to time we need to explicitly allcKate some 
puKussor time uj ilic Movie Ttiolhox so that it can do whatever 
it needs to do in order to keep the mtivie playing. This periodk' 
allociiion of processor time to the Movie 'foollxix is known as 
a movie, and we am accomplish it by calling the 
MoviesTask function over and over until the movie is done 
pkiying. So what we need to do now is provide a way lor 
QTMtx>VT(K>n>ox to aill MoviesTask periodically. (When w'e are 
u.sing movie conirollers, we don't need to ever c’all MoviesTask. 
tXfCau.se the MClsPlayerEvent functkin calls it internally firr us.) 

A stantbird way to do this, on the Muciniosh, is to insert a 
call to MoviesTask in the application's main event kx)p. For 
several reasons (whicli we don’t need tc j go into), well adopt a 
slightly lUffereni technique in QTMooVTtMjlixjx; wv'll call 
MoviesTask in response to null events (which occur often 
enough to keep the movie playing smtxHhly). For Windows 
applications, however, this is slightly trickier, since there is no 
Windows etgiivalent of the Macintosh null or idle event (and 
there is no main event !oof>). Pnil>:il>ly the best srdiition for 
Windows applicatiun.s would be tt> iirstall a timer that calls 
MoviesTask peritxlically. bor the moment, how'ever, well adopt 
a different (and iiuich simpItT) approach. Our Ixisic Windows 
framework already calls the function QTApp_HandleEvent every 
time a movie vvindcnv receives a message to piocess. Stj well 
iu.si lcx>k for null events there and aill QTAppJdle (which in turn 
calts MoviesTask) for every open movie w'indow’. listing S shows 
the changes w^e can make to QTApp, HandleEvent u> keep our 
Window^s imwies running smtx>tlily. 
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ri^sting 5; Getting Windows applications to call 
QTApp_ldle. 

QTApp^lhmdlcEvcnl 

(jTApp_ttandleEvGnt (EvetitReccrd *theE\fent) 

I 

Boolean m/IsHajidled “ false: 

//if TARGET OS MlHn 

WindowRefere^ooe myWindow = Nin*L: 
if (TheRvnnt 1“ NUU,) 

if (lIioEvgtiL >ii)hat = nullEveriL)' [ 

myWindow = QTFtanteJuetFrotitMDVieWindowO: 
while (my Window 1^ NULL) f 
QTApp_I[iie[ my Window): 

mvWindow = QTFrame GetNe^EtHovieWindowCiiiyWindtJw): 

I 

I 

//find I r 

rt'iumtmylsilandlGd): 

I 

Keep \n niiiicl iliat ifiesc sinitcgics iniglu not work for more 
compliaitecl or mortf sptreialized appilcatioiis. On the MaciiUrjsh, 
lor instance, an applkadon might he doing so mucii prfK'essing 
tliai Lhert' are not enough null events generait'd to keep the 
m{)vie playing snKK>thly. Qjnveisely, our Windows strategy 
might eonsLime too much processor time with its almost constant 
c alls to QTApp Idle. So rM(KiV’r(K>Ihox most tx^rminly does not 
provide a universal solution to the [)rohleiii ol when and Ikjw Lo 
call MoviesTask. Hie strategies that we've adopted here are 
dc^signed only [o keep the movies running smoothly, with a 
mijiimum of cljanges to our basic QuickTime framcwxirk. 

Preparing Movies For Playback 

So far. our applicaLion can open QuickTime movie files, 
read the tiiovies from iliosc Hies, and create appH^jirialely-si/ed 
windows to hold those iiKJvies. Are w-e finally ready to liegin 
playing the movies? In other words, when the user indicates that 
he or she wanus the movie to begin playing, can w e iu"^i the 
hall f'olUng by calling the StartMovie function and then let our 
frajTicwork task the movie periodically? 

The imswer here is: yes and no. We could indeed jitsl call 
StartMovie, and most movies would star playing pretty much 
immediately, as desired Other movies might require a small but 
oolicealile aiiKaml of lime to iKTlbnn sotnc necessary set-up 
activities, such as allocating huffejs to liold data from die movie 
file and setting up various QuickTime components to handle the 
procejis of dcx:omprc^ssing ihe data in the* file. This set up is 
imavoidable; howevei; if our application doevsn’t start the movie 
playing immediately, we can |x:rform this set-up right after the 
user op<ais the movie and before the usc^r actually starts playing 
the movie, so that it is effectively unnoticeable. This pro£:ess is 
called prerollin^ the [iiovie. 

Kor some movies — i n pa rticuiar, for si reamed movies 
kxated remotely on the web or on Ole .servers — prerolling 
alone is not sufficient to guarantee an ojXimal user ex]>eriemcL 
Ilia I s I^et'attse some actions need to occur even liefore the 
movie can succe.ssfully lx pie rolled. QuickTime needs to set up 
connections to the remote serv-ers and negotiate one or more 
protocols for exchanging data: it also needs to gel information 
alx)ul the types of data in those remote movies. This prcjcess is 


called /fnprerolltng the movie (Ixcause it needs to occur prior 
Ui the prerolling iirocess). Llnless we [>repreroil movies stored 
remotely, the movie playback W'ould lx annoyingly choppy and 
some of the data in tliose movies (for insLancCL the sound) might 
not play correctly at alL 

So we need a more genera! metliod of starling up movic^s 
that will accomtnodate botli kxal and remote QuickTime 
movies. We need t{) jirepreroll and prerolf our movies. Let’s 
consider thest^ operations in reverse order. 

PfCf oiling Movies 

To preroll a movie, w'e can use the Movie lo{>ll’!{>x function 
PrerollMovie. As indicalcxl afxwcL PrerolfMovie dtxrs whaiev(!r it can 
to piepaie the movie for immediate f>laylxick once ilie movie is 
started, T'his involves determining wiiat kinds of data are in the 
movie and .sculling up the appropriate ,software components to 
handle those kinds of data. Prerolliiig miglil also invtjlvc actually 
reading .some of the movie's data and getting the relevant 
decomprt:ssom ready to decompress that data. Itecxiuse of‘ this, 
PrerollMovie needs to know the cuiTcail Icxaiion in the [iiovie and 
the rate at which the movie is to lx played. We can get the curieril 
location in the movie by calling GetMovieTime, and we can get the 
movie’s ciefault playhat k rate by c.-alling GetMoviePreferredRate. So 
wx can [ireroll a movie by executing these lines of cixle: 

myTimeValue = GetNovleTlra*^CmyMovia, NULL); 
inyPlflyRate = GetMoviePrGfsrredRate(rnyMtivie) : 
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If for some rmson you w;inr to ckmge tlie current loe^uion 
in die niovie or die movie's default playlraek rale, you should do 
it before ailling PrerollMovie so that you don’t invalidate die 
work done liy PrerollMovie. You can set the curreni location in 
die movie liy calling SetMovielime, and you can set the default 
playback rate by culling Set Movie Preferred Rate. The default 
playback rate is the rate that StartMovie uses when it starts a 
movie playing. When you open a movie from a movie file^ the 
aclLial playlxick rate is 0 (that is, the movie is not playing). 

Prcprerolling Movies 

To prupruroll a movie, we can use the Movie Toolbox 
function PrePrerollMovie, which establishes any required network 
connections l^etween the computer running our application and 
the eomi:)Uter dial coniains the iiKwie being jireprerolled. If the 
movie resides on tlie same coinputer as the applicatiaii (that is, 
if die movie is a local movie), tlien PrePrerolIMovie has nothing 
to do and li returns iiumediaiely. As a resuli, iliere is no harm in 
calling PrePrerolIMovie for every movie our a[>[ilication o[ien.s. 

On the other hand, if the movie being preprerolied is not a 
local movie, then preprerolling it can take a significant amount 
of lime, partieularly if ihc local compuler needs to access die 
remc^te computer over a dial-up line. To keej^ your application 
from stalling while Quick'rinie negodute.s a connetlion with the 
remote compuler, you can call PrePrerolIMovie asynchronously, 
in which case PrePrerolIMovie returns almost imniedialely and 
then executes an apjilic^ation-defined completion function when 
tlie preprerolling is finisheiL PrePrerolIMovie has die same calling 
interface as PrerollMovie, cxcejH dial you must also specify a 
movie prepreroifing Coinpleikm rotifine and an optional 
reference constant tliat is passed to the completion routine: 

royPiayRate GetMoviePretercedRatetniyMovie): 
PrePrerollKovieCtnyMovie. 0, tnyPlayHate, 

^oviePPRollCoinpleteProc* (void NtheWiitdowObject) ; 

Here, gMoviePPRollCompleteProc is a universal procedure 
pointer (UPP) to the movie preprernlling completion routine. 
Q'rMnoVToollxix allocates this IfPP when it starts up, in the 
function QTMTJnit defined in Listing 6. 

Listing 6: Allocating a routine descriptiir for 
QTMT_Mo viePrePre roUCom pletePrc k:* 

(^TMT_lnif 

vcild Cn'MT_lnit (void] 

I 

// allucRlt: ii mutiivc JcKripior for our prt:prt:ri>IJ coiufjlcibn njoiint: 
gHoviePPRonCompleteProc ^ 

Nf^wMovlePrePreroUCoaiplfltpPrpc(QTTfr MovipPrppConiplfltf'Proc) i 
\ 

When the pieprenilling is compleie, the Movie Tch)IIx)x executes 
our movie [iiepreroliing eom[>letk>n function, deOned in Listing 7, 


[J«»ting 7: Kc?sp<>uding when a movie Is done 
prepreroilmg. 

QTMT_MovkPrt;PrcrollCompletePr(>c 

PASCAi_KTN void (JTMT_Hcivit?PcePcetollGoinpl<^LeProc (Movie 
tboMovie. GSErr theFrurolLlirr, void ‘theKefCon) 

I 

Ifpragma unused (thePreroliErr) 

WiadowObject myWindowObiect “ 

(WindowObject)theRefCon: 

Appllf!ationDat 3 Hdl inyAppD.ita = 

TSmeVulue myTlmeValiJe: 

Pixed my P lay Rsit e \ 

nryAppEata = 

(App11c ationD at aHd1)QTF c ame JJe tAp pD a t aF r omWind owOb j ect 

(myWindowObject); 

if ((tbeMovle = WULL) j| (myWindowObject “ NULL) || 

(myAppOata “ NULL)) 

reIurn; 

// prcmil I he ili;it it’s rf'-idy to ptiy when wc c;ill SfnitAkmc 

myTimeValue = GetMovieTlniettheMovie. NULL); 
myPlayRate ^ GecMoviaPreferredRatettheMovie); 

PrerollMovie(theMovie, myTimeValue, myPlayRate}; 

// for the pitiuitln-picturc movie, start it playing in a knip 
]f (thcMnvin = (**tiiyAppData). fPTPMnvIe) ( 
QTMT_ScLMovieLoopStalG(LhGMovlc, kNotmfilLooplng); 

StiirtMovie (theMovie): 


As you can see, our movie preprerolling completion 
function is quite simple. It really just prerolls ihe movie, thereby 
making the movie ready for playback. For some movies 
(namely, for QTMooVToolbox’s "picturc-in-picture movies''), it 
also starts the movies playing in a loop. We'll discuss picture-in- 
picttire movies later (in “Flaying Picture-1 ivFi cm re Movie-s"). 

Note that [)reprcrt>l!ing and pren>lling are* required only for 
movies that we are matiaging directly, using the Movie Toolbox. 
If we use the movie controller mcerface for managing movies, 
ihe movie controller auiomatk'ally preprei-olls and prerolLs the 
movies for us. 


PlAYlNG MOVreS 

N{)w w'c are finally ready to start our mtjvie playing. 
Assuming that a movie has already lieen prej:)reroIled and 
prerolltxi, we can set it in motion by .selling its rate to a non-?.ero 
value, using Llie SetMovieRate function. Or, we can simply call 
the StartMovie function, which .sets the movie rate to the default 
(or “preferred") m<»vie rate. Q rM(K)V'lbfslhox defines the 
function QTMT_StarlMovie (shown in Listing 8) to .stari a movie. 


Listing 8: Starting a movie playing, 

Q nvi T _ M uv iL-Prt MrtTVilt :^>mpktLFroc 

void Q.TMT StartMovie (Movie theMovie) 

I 

ir (llirMovIe = Nlll.i.) 
re L uni; 

// j| wc unuH kHjpiut; md wc’rc at Uitr end of tlic iiuivic. 

// return to ttic l>qtiniiiiig of the movie 
if {IQTMT IsMovieLooping(theMovie)) 
if (G^^tMovveTimefrheMovie. NULL) = 

GotMov i eDiirar t nn {theMovie)) 
GoTuBcgitinitig^OrMoviG f LlioMovie): 


StartMovie{theHovie); 
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QTMT_StartMovie checks io see whether a non-looping 
movie luLS reached its end; if it has^ QTMT_StartMovie cills the 
Movie Ttxdbox function GoToBeginningOfMovie to reset the 
current movie time to the beginning of the movie. If we had 
been playing the movie using a movie controller, the movie 
coniroiler would Iiave dime tliis for us. Since weVe 
programming at a slightly lower level, we need to do some of 
this housekeeping ourselves. 

Similariy, when we at^ playing a nondcx>ping movie using the 
Mewie Toollxjx and the movie reaches its end, its rate Ls not 
automatically set to 0. Again, this is some mmor housekeeping tliat 
we need In take care of ourselves. In this c:ase, well do the 
appropriate check in our QTAppJdle routine, delinc^d in Listing 9. 

IXsUng 9: Performing idJe-time tasks. 

QTMT^MovicPrcPriTOllCompk'tcPrtK- 

void QTApp_idie (WindowEeterenee theWindow) 

( 

GrafPtr mySavedPort; 

WindowObject jnyWindowOb ject ^ NITLLi 

ApplicationDataHdl ifiyAppDsta ^ NIJI.L: 

GetPort(imySavedPort); 

MncSoLPori (QTFtLi0]e_Ge^tPorti! roiDWiridoiifl{ef€?rence (theWindoy)) ; 

myWiiidowObjec t = 

QTFrame.GetWlndowObiectFroffiWindow{theWlndow): 

luyAppData - 

(Appli c at ionDat afid 1) QTF rame _ GetAppE a taF r oniWi nd ow 

fth^‘WlndrJw); 

if {{myWindowObJect 1=^ NltT-T.) (myAppData != MUTJi)) | 
i f f IQTMTJtvHCivIoLuupijigt (“inyWiJidowObjac L) . fMovie)) 

If (GalMo vie Time i ('•tnyWindowUbJ act). f^lovie. NELL) 

UetHovieEuration C (* *ntyWindowOb ject] . fMovia)) 
it (GetHovieRate((^'rnyWlndovOb ject}.FMovie) > 0) 
SetMovieRate {(* ‘inyWirLdowObject). fMovie, 0) ; 
if ((**!nyWindowOb]ect) .fMovie t= NELL) 

MoviesTaakt {**}iiyWlndf>wObjar.t) .fKovia, DoTheRightTh ing) ; 

if {r*wiyAppDaLa).IPIFNtJvie != NULL) 
qtht_U rawPictilleluFictureMovie(myWindowObJect): 

! 

NacSetPort(mySavedPort); 


QTApp_ldJe does tlircc main tilings. It .scLs llie movie rate of 
the movie in the specified window' to 0 if it isn't looping and it 
jjas piayetl tf> its end; it tasks the movie; and it draws any 
picaire-in-picture movie in the specified window. (Once again, 
well discuss picture-in-picture movies at more length later.) As 
you c‘an see, MoviesTask mkes two parameters; these are the 
movie to be tasked and a maximum number of niillisecoods that 
MoviesTask should spend doitig its work, Movies.h dermes Utc 
constant DoTheRightThing as 0, which means to service the 
Sfx;cincd movie once and then return. 

So, at last, we have at hand all die cs.sential elements of filaying 
movies using the Movie I'ailbcix. hirst, w'^e oi>en a movie file and 
load Uic movie from it (using the same Cfxle that we nsetl when 
pkiying movies using movie controilers). Tiien, wc pietireroll and 
pmfoll that movie, 'Ihen, we .start the movie playing by calling 
StartMovie. And finally, we periodically aiU MoviesTask to give the 
movie .some tiiiic to play. It’s okay to aiW MoviesTask < m a movie that 
has finished pkiying, so in QTAppJdle we don't botlier to clieck 
wheihei' the movie is aoiially playing or not. In faa, we shoukln't 
do lliat, since wc nccxl to ail I MoviesTask on a movie while il Ls 
preprerolling as well as wliile it Ls playing. 


Editing MovuiS 

Fditing movie.s is one of the tasks at which movie 
controllers excel A movie coniroiler keeps track of a movie's 
current .selection and allows us (for instance) to cut that selection 
from that movie by calling tlie function MCCut, like this: 

case IDH.EDITGUT: 

myEditHovie = MCCutCayMC); 
break; 

As you ctm scc% MCCut aLso returns to us a movie llial i.s the cut 
.selection, w'hicii we can put oti die scraji (to make it available for 
sufisequent pasting) by calling PutMovieOnScrap. Moret)veL the 
movie cxminjller keeps track of the enjnent adii slate of the movie 
tluit exists liefoa^ each editing oix-ration, so Util il txm rc'stoiv Uiat 
state if we subsequently call MCUndo. A movie's current edit .state 
cron.sists of all Uic infi^imalion that descTilTes the niovie’s contents, 
such as Uie sound and video data in Uie movie; Uie cuncTil edit slate 
also includes the movie's cunent selection. 

The Movie Toolbox provides a set of high-level movie 
editing functions, wlikli arc ju,st as easy to use as the functions 
provided by movie controllers. For instance, to ait the current 
movie selection, we can call the CutMovieSelection function. 

case lDM_m}tTCVJT: 

jityEditMovie = CutMovieSelection (rnyMovie) ; 
break: 

Siiiiilarly, we can use die ClearMovieSelection junction to clear 
the current movie selection Cihai is, remove it from the movie 
withoiil retaining the remcjved data). 

case 1DM_ED1TGLEM: 

CiearMovieSelectiDnliiiyMovie): 
break: 

Moreover, the Movie Toolbox provides the 
SetMovieSelection function, which we can use to handle the 
Select All menu item in the Edit menu, like this: 

cast' I0M_EU1TSELECTALL: 

SetMovieSelection(rayMovie, OL. GetMovieEuriition[myMovie)): 
break: 

'ITiere Ls one cotiiplication here: if we want to provide the 
.stanckird movie editing behavior witliout using a movie 
controller, then wc also need to keep track of the movie's 
current edit state whenever we peiform any editing opemtions. 
As weVe seen, the appliotion data record for Q'rMooV'l'oolbax 
contains a fickl IMovieEditState, of type MovieEditState, w'hich 
well use to lioid the current edit state. Before we call any Movie 
Foolbox function tliat changes the contents of a movie, we can 
call tlie NewMovieEditState funcifon to create a new movie edit 
state, as in tliis snippet from QTApp_HandleMenu: 

if {(theMetttjIr.RTn ™ TEH_EDTTGI.1T) || 

— TEM_EnTTPASTK) || 

(thcMenuTLcjik = TEOUITCLEAR)) t 
if ((*'jiiyAtipUaU). fHuvieEtlitState t= NULL) 

DisposeHovieEditState([**myAppData),fMovieEditState): 
(**myAppData}.fHovieEditState = NewMovieEditState(myMovie): 

} 
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Notice that we need to dispose of any existing' edit stale (by 
railing DisposeMovieEditState) before creating a new one. 
Otherwise^ we'd leaking memory. 

If the user selects the Undo menu item in the Edit menu, 
we need to a'instate the movie edit state that we have stored 
in onr application chita record. We do this by railing 
UseMovieEditState, like this: 

case Tim^RnTTUNTjar 

ir {{*‘myAppUiiLit} * tHovieKdiiStaLe ™ MULL) 

break: 

UeeHovieKdltiitatG(myMovie. ['‘myAppData).fMovieEditState); 
DlspoeeHovieEditState( (* ‘^myAppData) .fMovieEdltState); 
(**iijyAppData),fMovieEditState ^ NULL: 
break: 


if (ffiyWindDwObject i- NULL) I 
ioyAppData = 

{App1i cationDataKd1)QTF r ame GetAppDa ta F roiWindowObj ec t 

(myWind owObj ect); 

myHovie ^ (*'loyWlndowObjccL) . fMovie: 


if {(rnyWindowObject — NULL) || 

rettirtttmylsfiandled); 


(inyAppData = NULL) 11 

(nyKovie = NULL)) 


// beftire the Ciit, [^tc, and Clear otmmands, go the nirient edit state, 

// afttT dispcising cif the ctiraTilly-saml edil state 

if ([theMGniiltGin = lUM_EUiTCUT) |{ (ibeHetiul ton = 

IDH_ED1TPASIE) 1| (theMenuIteai = IDM_EDiTCLEAR)} I 
if C (• *tnyAppData). fMovleEditState 1 ^ NULL) 

DiBposeMoviGEdltState{ ("^'myAppUata). fNovieEditState): 

{''rnyAppData)*fMovieEditstate = Mey^ovieEditState CmyNovie): 


Once we Inive used an edit state, we want to disj>t>sc of it 
and set the stored edit state reference to NULL st) that we don’t 
reinstate the sanit‘ edii state twice. QTMooVl’fKtll^ox supports 
only one level of undtJ, just like tlie sUtndaal linear movie 
controller. In iheitry, however, you can NewMovieEditState and 
UseMovieEditState to support nniltipie levels of undo. 
Iinpleineniing this feature is left as an exercise for the reader. 

Tliere is one Imal compliciition to consider. If tfie usc*r 
selects the entire movie and then cuts the current st'lection, the 
resulting mt>vie is empty. It still exists, but it lias n<j video or 
audio data in it. Since the movie lias no video data, the movie 
lx>x is empty. Now, if we liatl perfonned this cut using movie 
conrrf>licr functions, the movie controller would have detected 
that the si/e of tlie nu)vie liad changed and would have noiifted 
our applicaiitKi by sending it the mcActionControllerSizeChanged 
movie controller action: m resfionse to this action we w'ould 
have called our application s QTFrame_SizeWinclowToMovie 
funclion. But we didn't u.sc* movie controller fumlions to 
peribnii the cut, so we need to handle this pos.sibility ourselves. 

'I he simplcsi way to handle this situation Ls [ust to call 
QTFrame_SizeWlrKjowToMc)vie wlienever wv pcifonn any ttliiing 
ojx^ratkai tliat miglit liave clianged the size of tlie movie, like this: 

if KtheHenultejn -- tDM EDITUNDO) || (theHenuItGii == 
IBH.EUTTaOT) (| (fh^'HpnijTtpm = IDH EBTTPASTE) || 

(tttr‘HpiiuTk'» fUM.EniTO.RAR)} i 

QTF r a mc:_S i /.r-W) nd owTo Hov i o (myW t nd owOb j cc I): 

(' •jnyWintlowOb Jecl), I ItfUi i ty ^ t rut*: 

I 


switch (theMeimltetii) 1 
// lidH menu items 

// Here we :iTe overridtrig Ute rtattiewurk's lidit meim luiidluig 
// Cwtiidi iKif.'i movie eonmillcTN). 

case TnH_KnTTtlNllO: 

// ncstoR* iIk' movie using tlu- eurft'ntly’Saved etUi st^iteahen d^ftose of It 
if ((**myAppDatal.fHovieHdltState NULL) 
break: 

UseMovieEditState(myMovie, {**DiyAppData).fMovieEdltState): 
DispoSGMQvleEriltStatp((•^myAppDeta).fHovieEditState): 
t**8tyAppDota) . fMovlcKdllStato ” NtltUa 
break: 

case IM_EDITCUT: 

DiyEditMovlG = CtttHovieSeiection(myHovie): 
break: 

rase Tm_KntTCaPV; 

myKtliLMuvie “ CtspyHovieSt^loelionfmyMovlc): 
break: 

case IDM^EUITPASTE: 

myEditMovie = NewHovieFroinScraptnewHoviGActive): 
if (oiyEditMqvie 1“ NULL) I 

PaBtrMov I eSf) rrl lontiayMovI n, itiyRd t iHnv Ir) j 
MsposeHuvie (fliyEdi tMovIe) ; 
myEdiiMovie ^ NULL: 

! 

break; 

case ID« EDITCLHAR: 

ClnarMovloSplecT Ion(ttiyHovfe); 

break: 

case iDW^hTUTSELliCTALL: 

SetMovieSeiection (myMovie, CL* GetMovielXiratioti (myHovie)): 
break: 


We now have all the pieces that we need to handle the Edit 
menu commantis without using movie conirtsllers. tJ.sting 10 
stiows ilie QTApp_HandleMenu runciion for QTMooVTooIIkix, 
tl'or readability, IVe cut out the Test menu handling,) 

Listing 10: Hancllifig Edit menu Items using the Movie 
T(K>lbox, 

QTApp ItandkxMcrtu 

Boolean QTApp^HamilcMDiui (UTfrtlfi thcHcnuTlcm) 

I 

UiitdowObJeci rnyWindowObject = NULL: 

ApplicationDataBdl loyAppDara “ NULL: 

Movie myMovie = NULL: 

Movie myEditMovie = MULL: 

Boolean my I Hand led ^ f«lne: 

myWIndowObjccl ” QTFrame.GoLWiridowObjGcLFrorifroiJiLWiridowt); 


//Tea menu items omitted hcn‘ 

dcfault: 
break; 

I //swiidi (theMenuTrem) 

// place any cut or copied movie segnumt onto the scrip 
ir (inyFAiiTMovio !- NUIX) | 

PulHovlcOnScriipfiqyRdl iHov \v, DL); 
UlsposeMovie(inyEdiLMovie): 

I 

// after cotnniands ttiat niigfit have changed Uic movie, sync up die mtjFvk: 

// window si/jc and mark the windtiw a.s diny 

if ((thaMenuTtent = TDM KDfTUHnO) || (thfiHRnuItetn -- 

TnM_li;r)ITCUT) I] (tlmMcnuTtcm — TDM EUTTPASTE) || 
(ihoMcnuIlon ^ ir3M_EDTTGLEAR)) t 
Qll'raPiOlseWindowToHovlG (myWindowOb j ect}: 

(' *iiiyWindovObject) ,tTsDirty “ true: 

1 

// for any Hdit menu command, inUiate that we handletl it 
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if (MENU ID(thellenuItem) =- kEditHenufieslB) 

myTiiHundJcci “ tftje: 

return(tiy[£rlbndled ); 

\ 

All in all, handiing thtf lidil menu items using Movie 
'r<x)llx)x functions is ntx ttK> much more complitiaicd than dt^ing 
ii using the movie control ler fund ions. We need to manage the 
movie edit sUUes ourselves, and we need to make sure to resize 
a changed movie. Ikit c)therwise the code b quite reminisiml of 
rhe movie t:onm>ller editing c:(Kle, 

Looping Movies 

In the previous Quicklime 7mikil artkie, you miglii recall, 
we saw Ik jw to read a movie’s kx>])ing state from some user data 
stored in the movie file. If a movie tile contains a user data item 
of typL' LOOP’, then the data in ihai item determines whether 
the kxjping state is normal kxjping (data is 0) or jialindroine 
l(X)[>ing (data b 1). If there is no such user data item in the 
movie file, then we assume that the movie ckx^s not lcx>p. To 
read a movie’s looping stale, wc defined die function 
QTUtils_GetMovieFileLcx)pinglnfo, which returns one of three 
constants dedned in (xir header file QTUtilities.!i" 

I 

kNarmalLoopln^ = 0. 

kPfllindromftLoopinfit = 1, 

kNoTLOoping - 2 

To set a movie’s looping state based on the k)Oj:>ing state 
.stored in the hie, we called the MCDoAction hint:! ion, passing the 
two movie contr<ilicr actions mcAcli on Set Looping and 
mcAcUonSetLoopIsPalindrome w'ith appropriate combinations of 
true and false. Now we want to see how to accomplish the .same 
thing without using ihese movie ctmtroller actions. 

To manipulate a movie’s iot^pmg state without using movie 
controller functioas, we need to work with the movie’s lime 
base, which defines the lime axmlioaie system of the movie. As 
hisiiie Macinlosh nicely (ifimses it, we can iJiink of a movie’s 
time base like a vector that defines die direction and vekxrity of 
time for a movie. A movie’s time base also tlefines the trurrent 
movie time. So it makes sense that lime bases are asstx:ialed 
with kxjjiing: nornial looping involves simpiy resetting the 
current movie time rti 0 once ihe movie time reaches the end, 
while palindrome looping involves reversing die direction of 
time wliile keeping the veitxity the same. 

l1ie Movie 'fcxillx^x creates a lime base for us when we load 
a movie. 'I“hereafter, we c’an retrieve a movie's lime l>ase by 
emailing the GetMovieTimeBase funclicm. Tlic movie’s kx>ping 
state is determined by some of the lime hose mntrolJfiigs, a 32’ 
bit value which we can get and set by trilling the functions 
GetTimeBaseFlags and SetTimeBaseFlags. Movies.h defines tiiese 
two time l>ase Hags related to looping: 

finiim { 

loopTitncBsse ^ 1 , 

palliitirqmeLooptlinc^asc “ 2 

\: 


These constants are interpreted as bil masks for the Lime base 
control flags. !n olfier words, you should think of loopTimeBase 
as 1L«0 and palindfomeLoopTimeBase as IL«1. As you might 
have gue.sscd, we can sei a movie's kMoping siaie by getting ihe 
current lime ba.se control flags, setting the approfiriaie bits on or 
tiff, and then setting the revi.seil time base control flags. Heres 
how we would enable palindrome |{K>ping: 

Tii[i€?Base niyTinteBase - GetMovieTlpieBasettheMqvie]: 
long myFlags = GetTinoBa£feFl^gs{myTimeBase) i 

myFlaga 1“ 1 oopTimp-BaHe; 
uiyFliiga I" pal j ndromnLoopTlinoRnnr: 

Ii e t T1 tnoBa a a FI ii g s (iiy'l* 1 Ha tie. my P1 a g a) i 

for optimal playback performanc'e, however, we should 
take one further step, whicfi is to set the movie’s pkiybuck bitiL'i 
to reflect the desired looping state. A movie's playlxick hints 
specify one or more optimization.s lhai the Movies Tcxikxix 
should use during movie play[)at:k. Once again, the playback 
liinLs are defined using individual bits in a 32'bii long word. 
These tw'o bits are dtTmed for setting movie kxiping hints: 

enum I 

bintsLoop ^ 1 « 1 * 

b i fits Pal i ndroHip = I 9 

I: 

The Movie Toolbox provides ihe SetMoviePlayHints fimction 
for setting a movie's playback hints, but there is no 
corresponding Get Movie Play Flints fund ion lo gel ihe tairreni 
playback hints. Instt^ad, SetMoviePiayFlints requires us to pass it 
a 32-bii ma,sk that determines which of the bits in the 32-btt play 
hints long word arc* to be considered, f'or example^ lo .sei the 
palindrome kxiping play him on, we could do this: 

SetHoviePlayaints EiheHovi?, hiniHUuup. h hui;1.r>op) ; 
SetMoviePlayHintsitbeMovie, hintHFalliidrgiife. liititisPu 1 Irulmine): 

The.sc iwo lines of ctxJe set Ixjth the kxiping and 
(lalindrome lixiping play liints to lx* active, (kemerntx^r that 
kxiping mtist fx' enabled in order for palindrome kxiping to Ix' 
enabled. ) And to set the movie play IiinLs lo disaf>lc any kxjping, 
we could execute tliis fine; 

SerHqvTpPtayHintnttheMovie, OL* hintsLoop | hintsPaiindrome): 

So, putting this all Logeilier, we .see that to ,set the kxiping 
stale of a movie, we need to set tile time base control flags 
appfopriateiyj we al.so should set the movie's playliack liints to 
optimize playback perfonuance. Listing 11 defines our complete 
QTMT_SetMovieLoopState for setting a m<wie’s looping state. 

Listing 11: Setting a movie’s looping state, 

QTMT SclMovIdjixjpiitaU: 

void QTMT_SetHovioJLoDpStato tMovio llitiMovio, UTfUS 
theLoopState) 

r 

TlneBaEe myTlmaiaa^ r 

long myFlagn = OL: 

if (theHtivle HULL) 
return: 
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iiiy Time Base “ CetHovieTlineBase(tii^ovie): 
layFlags - CetTimeBaseFlagsCmyTlmeBasej: 

switch (theLoopState) I 

race kNorBalLoapingr 

SolMovlcPlflyHirtta(theMovie, hintsLoop* hintsLoop): 
SetWuviePlayHintsCtheHovie* OL, hlrjtsFaiindroiie): 
myFlags |= ioopTlmeSase: 

layFlagc &-palindromeL&opTiraeBaj;©! 

break; 

cs^sfi kPallndromotiOoplTig: 

SelHfivlePlayJliritaJtht'Movie< hintsLoop, hlntsLoopJ; 

S e IM 0 V i eF 1 ay Jl i n t s it lieMo v i e . h itit a Pa 1 Ind rome ♦ 

hintaPallndrojae): 

myFiags 1“ loopTiffieBase: 

myFlage |=^ pallndrotneLtsopTiineBase; 

break; 

caae kNcjl^opIng; 
defaulC1 

nyFlags fir=^ '-IqgpTlineflase: 

nyFlags hr “paiiDdromeLoopTiineBaseT 

SetHoviePiayHintsftheMovle. OL. hintsLoop ) 

hinisPalindronie]; 

b reak; 

I 

SciTipelkiseFlags(iiiyTiiiieBase* oiyFiags); 


Tor certain puqxjscs, wc sometimes w;]m to know whether 
a movie is !iKjping and whetlier it Ls ]x*)indroiiic Itxipijig. Hased 
on what weVe learned so fai; we can easily define the function 
QTMT_ Is Movie Looping shown in Listing 12, which returns a 
15()olean value that indicates whether looping (either normal or 
palindrome) is enabled for the specified movie. 

Listing 12: Determining whether a movie is looping* 

QTMr_LMiivklxH>piu|i 

Boolean QTHT^lgHovieLooping (Movie theMovie) 

TimeBoj; e aiyT 1 me Ba se: 

long myFiags ^ OL: 

if (theMovie = NinJO 
tRtnrriffaloe); 

myTimeBase *= CetHovieTinieBase(theHovie): 
myFiags - CetrimeBaseFlags(inyTiaeBa£e}: 

returnf(Boolean)(myFlags B loopTimeBanp)): 

1 

And we can easily define lire function 
OTMT IsMoviePalindromeLooping, shown in Listing 13, to tell us 
whether palindtxnne kx}[>ing is enabled for the specified movie. 

Listing 13: Determining whether a movie is palijidroitie 
looping*_ _ 

QTMT_l5M f jy k'Ki lifian mK'ljoojhng 

Boolean QTMT_TsKovicFtiUndrotieLooping (Hovle theHovie) 

T imeBa s e niy T imaSa s e : 

long myFiags = OL: 

if (theMovie -- miLL) 
return(false); 

myTImcBtJSO ^ GetMovleTimeBasettheMovie); 
myFlage " GetTimeBaseFlags(myTimeBase): 


return((Boolean)((myFiags h loopTimeBaBe) && 

(myF 1 ags & pa 1 i nd rone LoopTiaioBa s e))); 

I 

Our apphcaiion QTM(Ki\rrtxillx)x iiscs these functions to 
set the appropriate check [iiarks on tlie “Lxjp" and “Ijtxjp Bac k 
An<l Forth” menu items in the Test menu, like tJiis: 

QTFraiBE_SetMaiiuItemCheck(myHenu* ID« SET LOOPING* 

QTMT_IsMoVieLooplng(myHovie) & & 

! QTMT_lEMoviePal indromeLooping (ifiyMf)V to)) ; 

QTFrame SetMenuItemChack (ntyM^nu * TDM_SKT_PALINDKOHJi_LOOPlNG* 

QTMT IsMoviePal!! nd romeLoop 1 ng(myMovlc)): 

PlAYlNG PlCri]RE-Ls-PlCTURE MoVUiS 

Last Cliristmas, I was hoping I hat Santa Claus wouid bring 
me a new television set, jx:rlia(>s a bit laigcr than the one 1 have 
now, and possibly also with the so-called “picture-in-picture" 
capability, where you c':in tune into a second channel that's 
displayed in a smaller Ik>x in the corner of the main picrure. 
Well, Santa wasn't that getierous iliis year* so I decided to see 
whether QuickTime could Itelp s;iti.sfy my craving to W'atch two 
vicleo souRX.^ at on^’e. (See Figure 4 once again.) It turns out 
that it's surprisingly straiglitforward to use the Movie T(K)lbox lo 
emlied one movie inside of another movie. Let's call the movie 
that we are emlxrdding the "pkluredn-picture movie” and die 
movie we’re enilx^dding ii into I he “main movie”. 

In the broadest outlines, wu want to open the movie file 
fh;U contains the picture-in-[>icturc movie, set that movie’s 
graphics pt)ri to txj the window lhai already contains the main 
movie, and then set tlie ]>klurc'in-piciure movie's endt>.sing 
rectangle to fit within the main movie window. Tlten we need 
U) ensure that the main movie doesn't draw on top of the 
[)kture-in-picture movie; we do this by setting the main movie's 
display clipping region to exclude the rectangle tx^:cupied l>y the 
pitinre-in-picTure movie. Finally, we need to task lx>tli movies in 
t)rdcT lo update the m<wie images and play the movies' sound. 
Let's see how to do tliese tilings. 

Setting the Picture-In-Picture Movie Geometry 

Since we want to draw the piclure-in-picture movie in the 
s;ime window as the main movie — and indcxxl on to[5 of the 
main movie — we need to set the grapliics port of the picture- 
in-picture [iiovie to the same grapiiics port used by the main 
movie. We can do that cjuite easily, like tlii.s: 

GetMovieGWorldCmyHainMovle* jhtnyGWorld, fftJT.L): 
SetMoviRGWorld(tiiyPTPHovJe, rayGVorlcl, NULL); 

lliit, we don't want to draw' the picture-in-picture movie at its 
natural si7.e. fnstaid, we want If to occupy some smaller portion 
of tlic main movie. For simplicity, well set the picture-in-pkaiire 
movie to have a widdi tliat is one-diird the width of tlie iimm 
movie, and a heigli! that is one-third the heiglit of the main movie. 

GEtKovleBox(myHainNovie * &rayRect): 

myValae ^ (niyRect.bottom - myRart-top) / 1: 
myRect.top 1= inyValue; 
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iityRec:t*bottora -= myValuer 

^ (myRef^t. right ’ myRcct. left) / 3: 
myRect.Ieft nyValue; 
myRect.right = myValue: 

SetMovieBoxlmyPlPHovle, imyRect ): 


Note thill this strategy will result in the picture-in^pktLire movie 
l>c‘ing distorted, unless its origiruil dimensions are profKjrtioniil 
to the dimensit^ns of the main movie. It wonid be easy, however^ 
to mcxlil’y this rode to reliiin the original proportkms of the 
pit:turL‘-in-pkture movie while limiting its largest dimension !o 
one-third the heiglit or witiih of the main movie, (This 
refinement is left as an exercise for ifie reader.) Finally, let’s keep 
track of the picture-in-piciure movie and its new rectangle in ilie 
application data .structure attached to the main movie window. 

t * * myAppDaTia). f P I PRe C t “ inyRe ct: 

( “myAppDatfl). fPTPHovie “ aiyPIPHDvie: 

Setting the Main Movie's Display Clipping Region 

If we simply slaneti playing tlie pictiiie-in-picuire movie anti 
tile iTtiin nK>vie using tlie geometry weVe set up so far, we would 
get an annoying llickering caused by the main movk image Ixring 
drawn over the existing pictiiie-in-pkture movie niiage, wlikh in 
mm Is then refreshed over tlie main movie image. To avoid this, we 
want It) set up tlie main movie so that it docesn’t draw within iht' 
retiangle tliiit encloses the pictiire-in-piclure movie. We can do tJlis 
by defining a new display clipping ngioti for the main movie, 

A movie’s disf)k4v difpirig region is the |iortion of the mtwie 
box in which the movie image is to be drawn. Tliat Is to say, tlie 


display clipping tegion defines a clipping mgion ih\i Is afiplied to a 
mtjvie just IkTor" it Ls displayed. (A movie also has a t lipfiing region, 
hut that legkm i.s applied niiK'h esirlier in file imaging [iifx:lme and 
isn’t relevant to us heie.) By default, a movie’s dis[>lay clipping 
region exactly coincides with its movie lx)x, but it's possilile to set 
any subregion of the movie ix)X iis the display c’lipping legion. In 
Lite ttuTL'ni situation, we want ihe main irKJvie’s iiis[>lay clipping 
region to lx? tlie rc'ctangle occupied l>y the main movie minus the 
ivciangle txcupied by tlie piaure-in-pktum movie. 

fo calculate this clipping region, we can use standard 
QuickDraw functions to get tlie legions corresponding to the two 
movie Ixjxes and tlien subtract one tegion from the other We set 
this region as the main tmwie's display dipping ixrgion using the 
SetMovieDisplayClipRgn Fund ion. Hus is all accomplished in the 
funaion QTMT_SetMovieCfipRegion defined in Listing 14. The 
Movie 1Vx>ilx)x copies the display clipping rt^gion that we pass it, 
so we ran ,s:ifeiy dispcxsc of ihai rc'gion, as well as the tw’o 
inUTiuc-diate regiom; we ust^ tcj calailate the display clipping 
region, IxTore exiling QTMT_SetMovieCiipRegjon. 


listing 14: Setting the display clipping region of the main 
movie. 

QrMHStlMovk'ClipRt‘sit»tt 


OSF.r r QT!fr_SetMovleCllpREgiori (WindowOb’f^Ct tbeWindovOb ject) 

i 


K«c L 

R^rkHandie 

RftnHandie 

RgnKandie 

App H c/j 11 0 nDat aUd 1 


myRErt; 

rnyMovIcRegIon; 
myPit'REgioti: 
uyClipRegion: 
myAp-pData *- MULL: 


Cisco 

Sun 

HP 

Compaq 

Apple 



Commit this to "Memory!" 


SGI 

Dell 

IBM 

Gateway 

And many 
more... 


Rocky Mountain Ram is a manufacturer of the highest quality computer memory . 
Upgrades for all major brands of Routers, PC’s. Apple, Workstations, Servers, Laptops 
and Printers. Rocky Mountain Ram maintains extensive inventory for fast service and 
factory direct pricing. All design, acquisition and manufacturing arc in-house. 

Rocky Mountain Ram has over 60 years of combined experience in the computer memory 
industry, and specializes in Government, Internet and backbone providers, University and 
Fortune 500 companies. Rocky Mountain Ram is dedicated to meeting our customers memory 
requirements in a responsive, knowledgeable, and supportive manner, 


Visit our website at www.ram-it.com (800) 543-0932 Fax (303) 413-8255 






// Kci rile apfilitariimspa-ilit’ dau 
myAppDiila - 

(App I IcaUunDaiaUd 1} QTFraiiw_GetAppDataFroiiiWindowClb jf^ct 

{theWindotoObjeOL); 

if (piyAppData “ HUIX) 
return(pararaErr); 

myMovieReglon “ NL'wR^nOr 
tttyPipRegion " NowRgrit); 
iiiyCl ipRugiun = NewKgn{J: 

CetHovleBoxt(**theifindowObject).fMovie. Amylect): 

Rec tRgn (inyMovieRegion < irayRect) j 

myRect “ {^'nyAppHatfl). mfRccl: 
if {[EmptyRRcr(AmyReel)1 

MacTnnpt Rr»ci (imykut' U kPIPESorderSize. kPlPBorderSize): 
RorLRgtiCniyPil^Regloiit ^myRect); 

Uif tRgn(i8yMovleR^gion, myPIPReglon, myCl I pRpglon): 

SetHovieDisiplayCMpRguff - “rhrWindowObjectJ, f Movie * 

myClipRegion): 

BI npuseRgfi {nyHo vieKeglgn ): 

Blspoy eRgu i myFIPRe gion): 

DisposeRgufipyCllpRegion): 

return(noErr )i 

J 


Notice that we call Mad nset Reel inside of 

QTMT_SetMovieClipRegton to exjjund i!ic piciure-in-puture 
rntivte h()X by a preset ainount (kPiPBorderSize) before 
convertin^j dial lx)x In ;i n‘gion. We dtj this to provide a few' 
pixels (if space in which to draw a lx>rder aroiitxl rlie pitiure-in- 
pirrure movie, which gives it u somewhat better appearance, 
fSec Listing li below for the code that draws the border) 

Tltere is one ririal tiling to keep in mind: if the main movie 
were being played Lising a movie controller t'ornponcm, ihen we 
sliouid stel the nawie display dipping region using the fLioetion 
MCSetClip insiead of SetMovieDisplayClipRgn. 

Playing the Picture-1n-Pictiire Movie 

Now liiai weVe opened the pictLire-in-piclure movie and 
)X)sitioned it within the main movie window, we need lo start 
the pictiirc-in-pkiiire movie playing and keef) il playing. All the 
les.sons we learned earlier in ^l^mparing Movies Fc^r Flay buck'* 
apply here as well, so we ll kick things off l^y preprerolfing the 
picitire-in-picture movie, like this: 

PrePreroilMovie( 0 ivPiPHovle* 0. 

GetMovl^PrsfetfedRatfi(myPTPMnvlc)< gMoviePFRg]iCompleteProc, 
(vaid *)thpWindowObJ f r t); 

WeVe using (he same movie preprert>lling eom|delion 
funtlion that we used lor die main movie, w'hich prerolls the 
movie as stKin as the prep re to I ling is aanpleted. Bui yoiTll recall 
from Listing 7 lhat the completion pnxedure includes a few 
extra lines that apply only to the pientre-in-pkture movie: 

if (fihpMovie (*“TnyAppUatti).fFlPMuvie) t 

t3THT_SotH(ivlcL(M>pState(theHovle. kNorEHalLooping); 
SLuriHavie(iheHovie)r 

1 

Sin<’e we‘re not going to provide a way for tiie us<?r lo start or stop 
the picture-in-picture movie, we call QTMT^SetMovieLoopStat© 
(defined in Listing 11) in stR the movie kK>ping state to noniial 


kxjping. ITttr movie will then keep playing, over and over, until 
we close ilic window' or replat e it with soriK* other pklure-iri' 
picture movie, Uten. we just call StailMovie to start the pictiire-in^ 
picture movie playing. 

So die only tiling thiit remains for us lo do is task the movie 
|X‘iitxliatlly to keep il playing kick smtK>ih[y. As before, this Ls 
something w'e want to do in our idle routine (QTAppJdle), where 
we are already tailing MoviesTask on the main movie. Wt: have 
several options liere. First, we totikl just add these few^ lines of cxxle 
to QTApp_ldlG, to explidtiy task the piciure-iii-piaure movie: 

iJ: ([‘UnyAupDataJ.tPIPMovie !- NtlLL) 

Movies‘i:ask( ('*myAppRata) .fPIPMovlB, DoTln^RlgliLThiiig ); 

(Ir, we could pas.s the value NULL as the first j>aranieter to 
MoviesTask, like liiis: 

HoviflBTafiktNUTa,. BoTlTcRigki'iliing); 

When we sfxx^tiy NULL in plat'c^ of a movie, were instructing the 
Movie Toollxjx to service ail optm movies Ix^fonging to the 
application, iiemenilx'r, ht)wever, tlial we want to draw a lK)rder 
anJimd llie picture-in-pkitire movie, tk) tlie option we'tl actually 
chtKise will Ix' to call an application (icfined function: 

if t (*‘fliyAppnata). fPTPHovlt? NULL) 

QTMT_B< riwf trmretriFictureHovietmyWindowObject); 

QTMT_DrawP(cturelnPtctureMovie simply t::ills MoviesTask on the 
pkuire-in-pictiire movie and draws a nice-looking, pseudo- 
grayscale border around the movie, as shown in Listing 15. 

listing 15: drawing the pkture-in-pkture movie and its 
border,_ 

QIMT 1 >niwPit ai rd n Picture Mwir 

USErr CjTMT^DravPictureJjiPictureHov ir* 

(WtmidwOlijecl llii’WiiidowObject) 

Appt trai ii>nll:il:aHat myAppUaLa NULL: 

If (ibnWUidowObject = NULL) 
return(paramErr): 

inyAppData = 

{AppiicationDataHEil)OTFr<jiiH» Get AppDrit nKromWimlowObject 

t tliffWiridowebject): 

if {oiyAppDatfl ““ NULL) 
rcliinif pHraTulirT): 

// ditiw ihcctinciu fnuiitr of lilt picuia-iii-picturit' movie 
if CC**iDyAppData).fPrPMovie [= NULL) 

MoviesTask{{*’■(nyAppUata) *fPII^Mov to, Bo’llioRJgliLTlririg); 

if UEmptyRoot (&(’‘myAppUata). iFlPReci) ) I 
PoivSiote my Pens t ate: 

Keel myRect: 

myRect = (*'niyAppData). fPIPReqt: 

// draw u iiM.’iHkj-govsi’afc bonk-f 
GetPenSrare(^JnyPpiiSLate): 

WatifiEetRectt^t*•myAppData).fPIPRect. ■kPlPEorderSIzp, - 

kPTfRorderSlze): 

RCBForeCoiort&gBlack); 

MacFraflieRect(&( **myApp!>ata) TPTPRc^rt): 
HacInr!etRert(&(**»rvyAppI)EUa) .fPlPRocL, 1, 1): 

RGBForeColor (frgWhiLe): 

MacFramcReciC&C**myAppData),fPlPRect): 

MacinsetRect(&{* * rayAppData).fPIPRect. 1, 1): 
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HCRFor(Crtlor{&gLGray) : 

HafFrami'^RocI **iQyAppDi)tsl .fPIPRect}: 

{••KyAppDaCa) .fPLPHi»ci = myRpcr^ 

SetPenStatfi(iniyPenStateJ i 

1 

rnf urn fnoRrr]: 

! 


Moving the Pictiirc-In-Pictiirc Movie 

Lcr.s hnLsh up by iiclding a simple cnhuticcmctil to our 
piaiire-in piftLiFc uioviu j>layl>ack capability: wliertcver the 
user clicks Ujc mt)use button when the cursor is inside ol tlic 
main mcjvie window, Ict^s move the picture-in-picture mtjvie 
so that its upper-lefi corner is at llie location <jf the click. Our 
basic cn)ss-[>latlbrm Quickl'inie (Va me work passes mouse 
button clicks to the appliealion function 
QTApp_HandleContentClick whenever those dicks fall within 
the window's ctmlent area. So all vve need to do is add somc^ 
code to QTApp HandleContentClick. 

Moving the piettire in picture movie rectangle is very 
simple. First, wc need to ctJiiven the |ioint that's passed io 
us iti tlie event record into Im^al coordinates: 

ipyPoint thfiEvent‘>wliere: 

G i 0 bo IToU>c n 1 (Aray Po t n t): 

Then we need to calculate the new movie box for the piclutt^^in- 
pknire movie. 1lie si/.t' of the movie Ixjx isn't changing, only its 
up^’HT-left comer So we am call MacOtfsetRect to ligure out where 
to place the movie l>ox and SetMovieBox to actually iia>ve it, 

Ha c Of f fjp tiH*c t {4 (‘ * my AppData) . f PI PRec t, 

myPoint.h - (**iiiyAppData),fPIPRect,lett* 
myPoUu , V t^’myAppData], fPIPRect ,top) : 

SetHovicBoxt *iiiyAppiJaLu). fPlPMovlo, 

' *!3ivAppD«uJ. fFlFKecl}: 


Finally, we need io rcialculate the display dipping region 
of the iiiiun movie, like ihis; 

QTffl'_SetMovleCllpltegion(myWl ndnwObJext); 

Tile complete procedure for moving the picmre-m-piciure 
movie in response to mouse clicks is slitjwn in Lisiuig 16. 


Usiing 16: Moving the picture-iii-picture movie within the 
main movie, _ 

4)TApp_F lfC,< mit'nrt ilidi 

void QTApp HandleContentCllcH (WindowKeference tbeWJndow* 
t Rec 0 rd ' r) 

[ 

CrafPtr FnyS>flivf!dPort; 

yifidowObjecL EtiyWIndoirfObj<sct. = NULL: 

AppiicatiorjDatalldl myAppDttla " MIJT.L: 

Gf^tPort(^mySavedPort): 

MarSptPart (QTFrjg hjp GetPortPromWindowReterence {11 k«W 1 iidtjw)); 
myHiriduwObjecL 

(Jl'Criiiiie^CetWindowOljJect FromWJ ndawtfhpyindow]: 
myAppData * 

{App 11 ca t i on Da taHd X 5 QTFr aii«_Ci? t App Da t aF r omW i nd ow (t HpW I ndaw): 
if ({mytfindowObject -- NULL) || tinyAppUaLa N!JI,L)) 
raturn; 


// movi' itw.' pkiiiif^rhpicturc niuvic n> iIk* specified Icjcaikm 
tf ((**myAppOata),ffIFHovie I* NULL) I 
Point myPoint: 

my Point = thcKvem >wLor(>; 

CiobaiToLocaKiemyFuln t): 

// if the main movie isii't pbyinR, crast^ the reefansde curn'iitly ocoipkxl 
// by the pLtitfC'in-fXciuit movie 

H 'ESQTHT IsMo¥l6PlayinR(t**]nyWindow0bject) .fHovie) ) I 
Reel myRm't: 


I 


tnyRect = (* * ntyAppDn t n). fFtFRect: 
HacInsetRect {AtiiykecL. kPI PRorderStKa^ 

EtasaRect{AmyRect): 


kPTPBnrd(»rSlxe); 


HaeOffaelRccl[fcC'myAppDflta),fPIPKect* 

inyFoini.b (*•tityAppData). f FIPReci:. left , 
myPoln t * v (*' niyAppDa t a) * f PTPRect, top}: 

SotHoviefloxt (‘ 'layAppDataJ. fFiPMovlc, 

kl* 'myAppUala).fFTPUpct): 

mH'lLSfjtHovipCl i pRpj?,iqn (iiyWindovd>b ject): 


MaeSetPort(mySavedFort); 
t 


CoNcnrsiON 

Keep in mind iliiU die [Kiint of this article is not that you 
should be playing movies using the Movie Toolbox alone, 
without the assistance of movie controllers. Indeed, as we’ve 
seen, tnovie conirollers do lots and lots of useful work for us, 
as well as a good deal of liumdrum hou.sekecping (such as 
setting the movie rate to 0 when the movie reaches the end). 
And movie conirollers liave a certain measure of built-in 
'Tulure compatibility'', as evidenced by the fact lhat movie 
controllers now pre[>reroll movies automaiically. 'flits means 
tliuF if you had written a mfivie-playiog application several 
years ago that used movie eoritrollcrs, you w^ouldn't have had 
[o change it inuch, if at all, to support the new si reaming 
movies introduced in QuickTime 4. 

Still, there are occasions when you mtghi need to 
manage a movie wiilioui using a movie eontroller, and we've 
seen (fairly exhaustively, I hope) w^hat you need to do to 
accomplish that. Bui, our larger goal here was to get 
acquainted with die Movie Toolliux itself, to gel a taste of its 
c apal}|lilies and to see how to operate on movies directly. As 
we steadily progress in our jfmrney through QuickTime, well 
come to depend more and more on the Movie Toolbox and 
less and less on movie controllers. 
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PROGRAMMER'S 

CHALLENGE 


by Boh Boonstra, Weslforcl, MA 


Sum or Powers 

A ycM or hnck, Ken Slez;ik wmte me tu say: “Recxrnily my 
71J3 ^nicle son showed me an extni credit math problem- Given a 
nnml>er from 1 tu 100, create dial imiii[x:r from one, two, or three 
srjiiared numiners urlded or subtracted together ... It turned out to 
Ixr niore difhculi than 1 iltought! Might diis make an inteitsting 
progmrnming diallenge?'' Well, Ken, we're about to find out. 

First, though, we need to spice up die problem a bit. Fve 
been trying to make the problems a litde easier tjf late, but the 
7^^' grade level, even t!ie 7’’ grade extra credit level, would l>e a 
l7it too ea.sy. l^rst, well ex[iand the problem rloniain to include 
any [JosiUve number that fits into a signed 32-bit long integer. 
Second, well ex[xmd the numl>er of terms allowed. And diiixJ, 
instcxid of limiting the ptoidem to only stjuared numbers, we'll 
allow any positive exponent greater than L 

Tile protoiy]x^ for ihe axle you should write is: 

typedet struct IntegerPnwer [ 

ion^ value: icrni isstj^iVviihk-^lxwtT*/ 

sho r t p owe r: /* ptwc r = 2,5>'lf .7 
^hort sign? /*+1 t5f I 7 
1 Truc'gcr Power; 

long r numtKT of factors 7 SuraOfPoverB f 

long result, r irrm^ nml m stun m ihls r-suIi 7 

IntegerPowet termfi [], /* n tum tt-rms sigii*vaiiic^pi»WiT iTctt 7 

long maxTerain T luajtitnum rnmilHrr t>r terms ;iIlowed 7 

); 

\bur SumOfPowers routine will l7e called a number of times, 
badi time, you must identify a set of terms which sum to the 
specibed result, latch term is a value raised to an integer power 
greater than 1, multiplied by a sign value. You should return the 
nurnfxT of terms u.sed to form the result, or xero if liie result 
tiinnoi lx formed with maxTerms terms. 

nie winner will Ix" die solution dial forms the desired 
results with llic minimum numlxr of terms. A lime jxnally of one 
term will be added per KM) milliseconds of execution time. All 
solulions must lx calculated at execution lime; any entry that 
precalculates a solution will lx discfualified. 

This will lx a nalive PowerPC Challenge, using llic 
CtxleWarrior Pro 3 environment. Solutions may lx* coded in C, 
C++, or Pasnil. Solulions in Java will also lx- ai cepied, but Java 
entries must lx accompanied by a test driver that uses the 
interface provided in the [iroblem .statement. 

Ken Slezak earns 2 Challenge [loinls tor suggesting diis 
month's Challenge. 

TifRFF Months Ago Winner 
Congralulatic^ns to Jonathan Taylor (Blandford, EJorset, 
ILK.) lor winning die Decemlxr, 1999, Q>stas Array Challenge. 


'Ihe Costas Challenge reejuined contestants to pnxluce all of the 
arrays of a given dimension that satisfied two criteria. First, each 
row and each column of the a nay must have exactly one “T, with 
the remaining entries being s^eros. Second, the line connecting a 
pair of Ts in an array may not have the sjtme slope as the line 
connecting any other pair of "Ts. Costas arntys have properties 
diat make it an ideal discrete waveform for some seasor 
appliauions. Tlie numfxT of Costas arrays of order N inoeases 
until N=-17, after which it decreases at Icusi until N"23. Ihis 
(Jtullcnge atiriuried I6 entries, 13 of which worked corrcxily. 

Jonadian's solution is recursive for array sizes greater than 17, 
but he g[tins speed by unrolliitg tlie ctxle for smaller orders, lie also 
itM>k advantage oi’ the fact that assembly language was pemiitied 
for tills Challenge. For these smaller arrays, lie maintained die 
position of the “r‘s in each mw in separate registers, eliminating a 
.signiheant number of memoiy accesses. Tliis optimization allowed 
Jonathan's entry to run approximiitely 15% faster Ulan the second 
[ilace entry by Ernst Munten Jonathan included a nice description 
of die recursive and unnollc-d algorithms in the prehice to liis code, 
so 1 won’t repealr his description hea^. 

I evaluated every entry by having them calculate die Castas 
arrays of orders S iJinjugli 13, ineJustve. I then extended die tests 
to include arrays of orders througli 13. Finally, I tested the top 
entries with arrays of orders through 17, In evaluating the 
correctness of die arrays generated, 1 made use of some ctxlc 
provided by Ludovic Nicolle. Ludo's code verified tliai each array 
produced mel the criteria for a Costas a nay, and dial each array 
was distinct from any other array. Solutions were judged correct 
if the numixr of valid, unitjuc Qistas arrays pnxluced equaled 
the known niimlxT of Co-stas arrays of a given ordt'r. Judging 
conednexs would have Ixen more difficult if any of die 
solutions had com[iieted [iroblems where the number of Costas 
arrays is unknown; fortunately (or unfortunately, depending on 
your point of view), none of the entries complcaed f>rf>blems of 
that size. Several contestants observed that execution time 
increased by a factor of -5.3 from one ordcT to the next, and 
some estimated that 1000 fast PowerMacs should lx able to 
calculate die arrays of order 24 in a couple of weeks. Perhajxs we 
should turn this over to the disirilKiiedmei folks. 

The table Ixlow lists, for each of die solutions siibmined, the 
cumulative time required to calculate the Ccxsias arrays up It; t>tders 
13, 13, and 17. It also indic:ates the code size, dati size, and 
programming language used by each stduiion. As usual, the numlTer 
in parentheses after the entrant’s name is the total numlxT of 
Cliallenge |x>inLs c-amed in all Challenges prior to this one, 
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Uvvv Is Jonthan Taylor's winning Costas solulkin: 


Tim(^{l3)Timc(l5)Timt'(l7)Efmfs tixk' lk\t:\ Ling 

(st'o) (scof) (sL'Oi) Size Size 


Joiiallud Tuylor H) 7.69 UM9 

12)6,12 0 

2133) 200 


l-rast Muntcr ($47) 9.31 27U.32 

1)77.0,3 0 

‘ififiH HfrfJS C++/aAin 

LudDvk: Nia)lli' (4«) R),02 2M9.(W 

m 0 

2612 2) 

C++ 

Xyii CirvKg (U6) 340.63 

N/A (1 

)42R H 

c:++ 

Uoh Sticyi er 1)1) 12.1X) 346.43 

K/A 0 

I5S720 10300 

C++ 

Willfki'Rii:kt;iH6n 19..«i 9K).(K 

N/A 0 

2)20 H 

c 

•liiinSiixumdWl i‘i.16 1U11,24 

N/A (1 

[3t)(J H 

c 

Grtfg ^ydtlsky (2) 40.74 1122.02 

N/A U 

2044 « 

c 

Mii-hiifl Ix-wi.'H 11.94 1592.36 

N/A 0 

1528 72 

c 

Runtly IRiringt 112) 57,32 IH(11.37 

N/A (1 

1516 2) 

C++ 

Sclxiiilian M;uirt‘r (77)59,83 1927.93 

N/A 0 

1216 7) 

c 

Hriiinlliill 125,35 .36)2,11 

N/A 0 

2880 412 

c 

Br.uly CIOJ 1.311311 N/A 

N/A 0 

1132 571 

C++ 

1). i., ft/A .M/A 

N/A I 



C. L N/A N/A 

N/A i 



il, 11 N/A N/A 

N/A 1 



Top Contestants 

SJsteel here iire tlie Top Contesianrs for the Programmer's 
Clmllcnge, including everyone who has aeaimiilated 10 or mt^re 
points during the* past two years, Tlie huiiiIkts lielow include 
points awarded over the 24 most recent contests, including 

1 K >inLs ea rned by 1 his monl h's entrants. 

l^ink Name Points Rank 

Name 

Points 

1 . Munter, Prn.st 247 10, 

Jones, Dennis 

12 

2. Saxton, Tom 139 11. 

Harl, Alan 

11 

3 . Maurer, Sebastian 

67 12. 

Duga, Bmdy 

K) 

4. Uieken, Willeke 

51 13. 

Hewett, Kevin 

10 

5, Hcidicoc^k, JG 

43 14. 

Murphy, ACC 

10 

6, Shearer, Rob 

43 15. 

Selcngul^ Jared 

10 

7. Boring, Randy 

39 16. 

Snout, Joe 

10 

8 . Taylor, jonalhan 

24 17. 

Varilly, Patrick 

10 

9, Brown, Pat 

20 



11 )ere are three ways to earn points: (1) scoiing in the top 
5 of any Challenge, (2) lieing the first person to find a bug in a 
publislied winning soluliun or, (3) being the first penson to 
suggest a Clialleiige tliat 1 use, llie points you can win hvq: 

Isi place 20 points 

2 nd place 10 points 

5rd place 7 points 

4ih place 4 points 

5th place 2 fXiinLs 

finding bug 2 points 

suggesting Challenge 2 points 




Ci^fitas.c 

Copyright © 1999 Jonathan Taylor 

r 

Tlic atgrtrithm works by jjttcmpting to find a position for a ‘1' in tlic first 
row of tile array, aiitl tticii tt> work down itie arniy aUciupUng lo (HI cadi 
row in mm ntuil ilierc is no pertnissihJe move, in wtiidi case Lite 
program backtracks to tJie previous rxwv anti tries the next permissible 
fKJsition. At the beginning of each row, it calculates a bit-mask which 
shows which positions have been forbidden by the choice of position 
on the previous mws, 

'lliciv arc two conditions lliai are detected: 
t A 'T is already in the column 

2. IHitiing a ‘ r in tliis position would create tliree in a row: 

Let a A and B be the x p<Jsition of the' I ’ in two previems niws. Every' 
existing combination of A and H is checked in mrn.C is another row's x 
position.This row is the one which, w^hen combined w^ith H ami C will 
cause one of the positions in the curfcni r<>w to bt' forbkldcn. For 
example; 


1000 

0000 rov 

described 

by 

A 

0000 

0010 



0010 

0000 row 

described 

by 

B 

0100 

0000 row 

described 

by 

C 

000] 

GOOD 




(the next row is the one cuffently being deter mined) 
the' r in row 13 is two right and two down of the one in A. so the 
position two right and two down from the ‘ T in row C is forbidden,I hc 
[migraiii will record this information appropriately 

The program was a recursive function which stores the position of the I 
in each niw (rowPos) in RAM, as well as the bitFiekl for each row.The 
hit Field is a long where each hit represimts one tif the positions that the 
' I' could be placed in the current row. If a bit is set, that position is 
k>rbiddcti by the rules as applied to the rows that have already been 
decided. Unused bits arc also one. Note tJiat each level of recursion has 
its own bitField variable, eiicli <jf which will lie very different. 

In each recursion, it sets brcFickl to the appropriate value. If bitField is 
now ecjual to 

'I, there are no permissible places to put tlieM'^on this row,and the 
function retiirns to the previous recursion. If it docs not return, it then 
checks each bit in bitField hi sec if it is a If it is. dial is a 
l>crmissihlc place for ihcT. U records ibis selccUon and cafis the next 
level of recursion (when tliiit level returns, execution will resume by 
try ing the next bit in bitField), 

If by placing a M' at this level the array has been successfully filled, the 
array has the correct values entered in it, and the function then returns 
to tile previous level of rcciu-sion in order to c<m[ini,ic die search for the 
next solution. It should be noted that if an array is a valid solution, then 
its liorizonutl reOeciion is also a different, valid solution (for 2 or more 
ix>ws>.That is also rcctinlcd in the solution list.This allows the running 
time to be roughly halved, because once the first row has been hah 
traversetl, all the solutions w'ill have l>een found. 

Tlie problem with iliat is d^u the pnignun must lx: siopiJcd luUfway 
tlirougli the iirrays order to picveth ihcai: Ix-ing repeaLs. fhe condition is 
sligliil)' different for eveI^ iuid odd’Sized arrays, so one of two dinerent tests 
is used depending on the array size. 

This version was used for cases of n> 17.Version 2 bandies smaller cases 
(much faster!).nie underlying algorithm is the s'ame, though. It could 
easily be cx!ctide<l to higher ones by writing more code. 

Version 2 

I suspected tliai the limiiifig factor for the speed of die previous 
example was probably memory accesses. In calculating bitField, the 
positions i>f the ' Us in previous ix>ws are iisetl over and over again. 
However, they are not used in order, and neither 1 nor the compiler 
could find any effective way of caching tlic values in registci-s to save on 
RAM accesses. However, I realised there were in fact enough registers to 
fit them all into registers. 

Thi.s strategy is extremefy' fast, as it requires only one write to RAM when 
calling the next recursion level, and one read when returning. Htiwever 
there i.s a problem. I have been unable to discover a way of indirectly 
addressing a register. It is not possible to design a loop that wdll access. 
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Kiy^ row^positionlnl if it is stort-s in rt!gist£:i- n. It wus tltt^'forc nt:t't:ss4iry 
ro unroll all the loops completely (If Jinyonc wants to tell me how I 
could have pcrfoiiiied indirect addressing of registers, I'd love to know!). 

Since the loops were of variable length depending on the level of 
recursion, it was necessary to write new ctnfe h^r every level of 
recursion, with 'goiti's to "call” the next level of recurs ion. This has the 
huge tlrawback that new code must be written in order to allow the 
program do determine larger arrays.The competition code was able to 
deal with up to 17x17 arrays. What I shuukl have done was to write a 
prcjgtajn to generate the C code, since the unrolling is eoinplctcjy 
detemiinisLic, although fairly complexes it was, 1 had to spend a long 
time checking ft)r erntrs in the unrolling. 

By the 17th mw, there are HO calls of SetBlt{)n'herc are only 17 bits to 
be set.This is a huge ttverkjll if it turns out tht*re is no place to go anyway! 
As a result, I inserted the line; 

if (teirtpBitField=-l) goto endSotForbiddenXX: 

after every 5 SelBitC) s.lhis allows the subsequent calls to lx." skipped if 
there is already no place left to go. I have no idea how often they should 
bt! put - T dttin'l have time to experiment - anti they take up valuable 
execution time. With some serious ex|H"rimentation, a Ixaicr tlisirihiition 
of the ‘if's could almosrt certainly be found. 

This version has several I imitations.'Hi c prtiblem of loop unojlling 
limiting tlie array siite can lie partly solved by pitKlucing an automatic C" 
code generator as descril:)ed.The other potential problem is lack of 
registers. I reekon about are needed in addition to the row-pc^sition 
ones.With current j->rocessors having 52 integer registers, 22x22 arrays 
could potentially be calculated. After that, the values would have to spill 
over into HAM, causing some, but not iniitally much, slowdown. 


7 

# include "ContanJT* 

#include <MacTypcs.h> 


a this macro is the asscmtjly co<lc for the detection of a Uirccdti a-row 
// situation 

lld&finfi SetBlt (A, B * C) add rO,A,B: 

\ 


\ 

r0.k0n6.r0: \ 


sub r rO * G H rO: 

slw 


or 

tampBitField »tempBitField,rD 


// this macro is tht; assembly c<Kle ff>r detection of an already-fiHe<l 
// column 

^define IladBit (A) siw rO»kOne,A: \ 

or tetupBit Fie Id .tempBitField .rO 

^pragma optitnizatlon level 2 

/* 1 don't remember exactly why this was needed. If the level is itero, the 
Tegi.sler' keyword.s are ignored. If it is too highj maybe it )ii.st took for 
too long to compile without gaining anything... V 


void DoCofitaijRow(long row) ; 

long EnumerateCostasInRegistersdnt n,unsigned long 
‘oostasArrays); 


1 ong gCount,gMax Rows; 

un s i g n ed long ' gCo.'^ t a .“^A r ra y a : 

long HnumerateCostasCint n,unsigned long 

*costasArrays) 

t 

ifCn>17) 

1 

gMax_Rows ^ n: 
gCoa t a.sArr ay ost as At ray s - 

DoCostasR£>w(0j : //call recursive ftmction 

returntgCount): 

] 

else 


return (RnumerateCostasTnRegi sters (n .costa.'sArray*;^)) ; 

) 


void DoCostnnRowC1ong row) 


register long 
static long 
static long 
static long 
static long 
static long 

static unsigned 


n ,iu. bit Field .biLNum: 

doExlt: //used to agnal when all anays Ibund 

count: //number found 

ma x_ r ow s • //d im en,sjtj ns of array 

blankBitField; 

rowPosStore [321 : //x position of the * I' 
//in each row 
long *costasArrays: 


it (row “ 0) //setup code 

I 

count “ 0; 

max rowE = gHax Rows: 

b]ankBitField = (-1)^(fl<<raax rows}'!): 
costasAr rayn^gCostasArrays: 
d.oFxit=£alse; 

1 

// Phis next bit deicels whicli jxisilioos arc fbrl>icJdcn 
// See ill trod Liction for more details 

bltField = blankBitField; //make all x positions permissible 
for(n=0:n<row;n+I) 

I 

bit Field |^( l«rowPosStore [n] ) : //forbid (condition *1) 
f or (m^G :m<n\ m++) //Rxhid (condition #2) 

bitFieid |= {l« 

(rowPosStore [n] frowPosStore [row-l-mj - 
rowPoflStore[n-m-11)): 

] 

If (bJtPlFlld =1) 

return : //all positions are forbidden 

for (bitNuin=0 : bitNuiii<inax_rows r bltNum-H-) 

//try eacfi ]x>sitiim in turn 

J f c (bitFieid^ (i<<hitNum) ) “= 0) //pennisstblt 
I 

//Next coines ctxle for checking when we are done 
//(sec introduce on) 

if ([nax_rows142 = 1) //tKld-8ii!:cd array 
[ 

if t row=l ) 

I 

1 F(b H Ni[in>iiiax_rowf;/2 
rowPo EjS tore 1 0 ] ^^iTiax_rowii/ 2) 

t 

gCount=count: 
doExit“true: 
return: 

I 

I 

1 

c 1 ae? 1 f (£ ow^O) //even 

[ 

if (bitNum>-tiTax_rows/2) 

gCount*count: 
return: 

f 


rowPosStore[rowj = bltNumr 

if Crow ^ Tnax_rows 1) //got a eoinplctc array 

t 

f o r C n=0 ; n < ma X r o ws: n ++} //re*c( ird it 

conranArrayn [enutu *ii]ax rowfi+nl = 

(I« rowPoaSiore [n]) : 

counl-H-; 

lfCmax_rows != 1) 

I 

for Cn^O:n<tt]ax_rows:n++) 

//and its horizontal reflection 
coGtasArrays [eoiint*max_rown+nl “ 

((!<<( iiiax_rown 1 ) ) > > rowPonKt o re f n ] ) ; 
count++: 

I 

else //array is 1x1 - got ilic solution so exit 

gCount^Count; 
return: 
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Df) C€ifi I a «Rfiw C r dw+ 1) ; //caU titxt level af recursion 

t r fdeKjcl L 3 return: //in scl wlicn all arrays ;irc round 

I 
I 
I 


//define STORED 
//define STORE I 
//define ST0RE2 
//denno ST0RE3 

J define STORED 
define STORES 
//define STORES 
//define STORE? 
{define STORES 
{define STORK9 
//dnflne STOKE 10 
//define STOKEll 
//define STORE12 
//define STOKE13 
{define STORE14 
{define STORE15 


RPOO-bliNum 
RPnt^bHNnm 
RPOa-bitNum 
RP03=bitNum 
RP04-bitiaum 
RPOS-bitNum 
KP06=bltNum 
RP07=blTNum 
RPOa^hi i NuJn 
RP09-blLNuiii 
RP10=bitNum 
RPll=bitNum 
RPi2--bitNim 
RP13-bltWijro 
RPH=bltNum 
RPI^-bI I Mum 


//def 1 ne 
t/de r i ne 
//define 
{define 
//define 
{define 
{define 
{define 
//define 
{define 
{define 
{define 
{define 
//define 
//define 
{define 


TpOADO bi LMunt^RPOO 
LOADl bitMmn=RP01 
LOAD2 bitNmii-RP02 
L0AD3 bitNunr=RP03 
LOAD4 bitNujn=RP04 
LOADS biiNiiiir-RPO'S 
LOADfsbltMiiai=RP06 
Tf)AD7bUNuni=RP0 7 
LOADS bltNuiii=RP0H 
LOAD9 bltNum=RP09 
LOADIO bitNum=RPlO 
LOADII bitNum=RPll 
L0AD12 b±tNutn=RPi2 
LOAD 13 bir.Num=RPI3 
IX>ADU bnNufn=RP14 
LOAD I 3 biLNuin=RPlb 


lonj^ EnumerateCostasInRegisters (itit n, 

unsigned long * coat s fsAr ray n) 

I 

register long bitField r 

/* this is a SCI of bits that records whkli 

positions arc forbidden dtic to the choices 
for prcvUius mws.A' F tncans the position 
is forfntldcn V 

register long teJBpBitField: 

/* when a ik'w level of recursion is l-jcgun, tills 
stores the new value of bitPicld as it Is 

calculated. Rut if tht^re arc no leg^l pHisitions, 
an immediate return (KCuts. bitFicId is only 
updated if there is at least one position, since 
the bitl'ltid value for the previous recursion 
level inusl lie aUyrcd in HAM - a slow pnazess! 7 
register long bitNum; 

//die twretit X position tn the row Lindt!r eonsklrrmtion 
register long blnnkBitFlold: 
register long kOne; 

//Cl ale Is if Ibis is a icRfstcr instead of a constant 

register long 

RPOO.RPO1.RP02.RP03.RP04.RP05 * RP06.EPO 7, 


RP08.KP09,RPIO,RP:1 .RP12.RP13 .RPlA.RPi'): 

//RPn ("row position n'> stores the x cxMindinate of the * I ‘ on row n 
long bitFieldStore[ 32 ] : 

/• these store the hit Fields as e^ileulated for previous recursion levels 
1 ’hL 7 must be tdoaded after a return to a previous recursion level */ 
long count: //number of solutions found 

k0ne=l: 
eount^: 
beginOt 

biankBitFinld^C-1C(kOnc<Cn) 1); 
bit:Finld”b1 £mkBi iFleld; 
bttFleldSLora[Oj-bitFieid: 


f or CblcNuin=0: bitNuii<n: ) //try every x position in turn 
I 

if C tbitField& CkOne«bltMutn) )--0) 

//if this position not forbidden 


I 

//RtJwP<>sbtorel row] =bitNum- 
STORED; 

1 f {n==l) //record layout! 

I 

costasArraye[count‘nl=C1<<RP00); 

//record in result array 

count I i : 

return counl ; //return mnnher found 

1 

goto beginl: //try ihc next row,*. 

I 

returnPointO" 

bitNum+fi 

I 

doReturnO; 

return eountj 

boginl: 

tempBitFieid-biankBitFieid: 

asm I Had Bit (RPOO) j //can't be hekiw the^F in the first row 
bltField^empBitFleld ; 
bitFieldStoro[I]"hltFleld; 

fo r f b 11 Muiii^O: b 1L Nutn< n ; ] 

I 

if (CbitFieid&(kOne<<bitNuiii) 
i 

//RowP<>sStore| now j=bitNum; 

STOREl: 

i f C n“=2) //record layou t! 

t 

if{RFOa>=n/2) 
return count: 

cost a s Ar ray s 1 count * n] = (1 «RPQ0) : 

COStasArrays I count *n4 n“( I C<RP01 ) ; 
count 11: 

conrasArrays[couni*n]“{2>>RF00 }i 
roolasArraysi [count'n4'l]^C2»RFOl3 : 
eount-H-; 
goto doReturnl: 

I 

goto begin2; 

1 

returnPointl: 
h 1 r Ni]m++; 

1 

doReLurnlr 

// bii N um=RowlA>sStti re| now 1; 

LOAOO: 

bltFleld^^bitFieldStorefOl : 
goto returnPolntO: 

begi n?. \ 

tompBitFJeld^blankBitFleldT 
seLForbidden2: 

asm i HadBit (RPOO) I //set fortudden bits {condition *1) 
asm I HadBit(RPOL) I 

asm I SctBitCRPOl .RPOKRFOO) 1 
//set fbrbidtlen bits {condition Ji*2) 
omlSn Forbidden^: 

i f (t empBitField=^* 1) 

//give up now if no ixjsiiions pcrruitied 
goto returnPointit 
bitFleid—tcMpBitFleld: 
bitFieldStorc!2]J tField: 

for (hi T.NiJir“ 0 : bl L NumCn :) 

I 

if ((bltField&CkOne<^bltMum) 3'“^) 

( 

//How PCRtSiore I itjw'1=biiNum; 

ST0RE2: 

if C n”3 3 //recorfI layout? 

lf<Kt01>n/a («f» HP00=n/2) 

return count: 

costas Ar ray s [count * a] (I «RPOO ) ; 
costasArrays fcount'n11]^(I<<RP01); 

CostasAr rays[count *n+2]”(1<<R?02); 
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countH t: 

coHt.nEiAf rayji [count *111 — C4>>RP00) ; 
costasAr rays icount*n+l]-C^i)‘>RFoi) 
cos t^isAr rays [count * n-i-2 j - (4»RP0yt) 
count++: 
goto doRatUrnl; 

1 

goto begins; 

[ 

returnPolntS; 

bilNum-H-; 

1 

doReturn2: 

// bilN um~ Row FosSiorc | row |; 

LOADl: 

bltFieid—bitFieldStore[ 1 ] ; 
goto teturnPointi; 

begins: 

t empBltFleid^bl aiikBitField i 
setForbiddenJ: 

asm! HadBitCKPOO)1 
asmi HadBltCRPOl)J 
asm I HadBitCRP02} I 

asm I SetBit{RFO2,RF01,RPOO) I 

asral SelfliL{RP02,RP02,RP01) I 

asraf SetBitCHPOl.RP02,RP00) I 

endSetForbiddenS: 

if(tempBitPield”^'1) 
goto roturnPoint2; 
bltFicld-tempBItField: 
bltFieldStore[3]^bitFleld: 

fo r(bicNum-O j bitNomCn:3 
( 

if { CbitField^ {kOne «bl tNum) ) ) 

[ 

//Ho wPosStorc [ row] =b i t N ii m; 

ST0RK3; 

if(D™43 //itCtuxItiiyoiTt! 

f 

ifCRPOO>-n/23 
return count; 

coRtasArrays[count*nl=(1<<RP00); 
cost asArrays [count “ n41 ] ■= (1<<RP0J) 
costasA j: rays [count ‘n+2] •=[ 1 <<RP02) 
costasArrays[count“n43]=(1<<RP03) 
count++: 

costasArrays[count‘n|=(B>>RP003; 
cofitasArrays [count * n+1 J [8>>RP01 J 
eost-asAr rays [count* nt2] = C8>>RP02) 
costasArrays[count*nf3l^(8>>RP03) 

counL4+; 

goto doRcturnB; 

[ 

goto begin4: 

1 

returnPointS: 
bitNumti; 

.] 

doReiurn3: 

// hit Num^^RowBjsSioiv | row 1; 

HJAD2; 

bitFieid=bltFleidStore[23: 
goto returnPoint2; 

begin4: 

tcmpBltFiold-blankBItFietd; 

setForbiddenA: 

asm! UadBitCRPOO) 

HadBit(RPOl) 

HadBit(RP02) 

HadBitCRP03) 


endSetFo rbiddeii4: 

if (tenipBitField= 1) 
goto retumFointS: 
bitField=^tempBitFieid; 
bitFieldStore[4]=bitField: 

To r C b I tNum=0 ; b i tJNtimCn; ) 

[ 

if C {bl LField& CkOne«b 1 tMtim) )“0) 

I 

//Row PosStoicI row I -bit Num; 

STQRE4: 

if C ri™5 3 //record layout! 

t 

if(HPai>n/2 RPOO=n/2) 
return count; 

costasArrays [count * n] “( t <^^RPOO) ; 
costasArrays[count *0+1] = (l<<RPOi): 
costasArrays[count'n+2]“(l<CRP02); 
costasArrays [count*n+3 J = ( 1«RP033 * 
costasArrays[count*n+4j“(l<<RP04); 

Coijnt++: 

CoStaEArrayfl[count*nl=(16>^RP003; 
costasArrays [count*n4! ] = ( 16»RP01) ; 
costasArrays [counL*n42] = { 16»RP02) ; 
costasArrays [count * n+3) = {16 »RP03); 
costasArrays [count‘n+4j =(lb»RP04): 
count 44; 
goto doReturn4: 

} 

goto begins; 

I 

returnPoint4; 
bitNum++; 

J 

doRet lirnA: 

// bitN 11 m=RowPosSt<^ re [ n >w ]; 

L0A03; 

bitFleld=bitFieidStore[3]; 
goto returnPointB; 

begin5; 

tempRit.Field“blankBitField: 
setFotbiddenS: 

asm I liadBltCRPOO) 

HadJiitCRPOl) 

HadBitCRP02) 

HadBitCRP03) 

HadBit(RP04) 

Set B11(RP04,RPO1,RPOO) 

SeteitCRP04,RPOa,RPO1) 

SetBit CRP04 .RF03,RP02) 

SetBit(RF04 * RP04 * RPO 3) 

SetBit CRP03 * RP02 * RPOO ) I 

/*Tn must CLiscs lur large row iiuinlHrrs, 1 suspect that all jxjsitions will be 
very t|uickty seen to be furbiddcir AM the sul>M:t|ucni SciBitO calls an" 
unnt;ccssary tn that instance/niis check alitjws them ni lx; skipjxd otfct. 
It appesirs after o'ery five Setliitc) culls (sec iiiiroducik)ii fur coiiimenis) 
V 

if [ tempBit Fi e id^- 13 
goto endSetForbiddenbT 
aatit I 

SetBit(RP03,RP03*RP01) 

SetBit{RPG3,aP04.HP02) 

SetBit CKP02..RP03. RPOO) 

SetBit{RP02.RP04.RPOI) 

SetBit(RPO1.RF04.RPOO) I 

endSetForbiddenS; 

if {tempBitField=-1) 
goto returnPoint4; 
bilFiold-tompBitField: 
bitFieldStore[5]-bltFleld; 


SetBit CRP03.RP0I.RPOO) 
SetBit{RP03.RP02.RP01) 
SetBit CRP03.RP03.RP02) 
SetBit(RP02.RFD2,RFDO) 
SetBit{RP02.RP03.RP013 
SetBit(RPOl.RF03.RPOO) 


for (bitNuiii= 0 ; bitNum<n;) 
i 

if C CbitField&(kOne<<bitNum))““0) 
[ 

//RuwPosStore[ r«w]=bLtNum: 

STORES; 


78 


Pboorammer’s Challenge 


MacTecu • Mahch 2000 















wtDinesign 

Sdevelopment 


where weh pro: 


PLATINUM SPONSORS 


SILVER SPONSORS 


WWW. 


SCALA 


















ir(n'^6) //nt'irorcl layout^ 

I 

if(HF00>=Ti/2j 

return count: 

costasArrays[count*nl^(i<<RP00): 
costasArrays fcount*n+ll”{l<<RPDl}: 
costas Arrays f count* — {J<<RPt}2) : 

cost asArrayti f count ‘ n+ll "C 1 <^KFC>^) ; 
cosiaaArrays [count *n+4i'^C I <<RP04) : 
costustArray® [count *n+5]- (1«RP05) : 

count-H-; 

coatasArrays[count"nJ=(32>>RPOO): 
eostasArrays[count*n+lJ=(32>>RP013 : 
coatasAr rays [count"ni 2l^{32»RP023 ; 
costa nAr ray a [count* n+3l^C32»RP03) i 
costanArrRys [count*n+4]-(32»RP04) i 
caa LUuAr ray® [counL "n+^] '^C32>>RP03) ; 
count-H'i 
goto doReturnS: 

J 

goto heginfi; 

I 

retu mPo i nt5 : 
bllNam++: 

I 

doReturnS: 

// bilNtJm=Row|4K>Stiilx:| row |; 

LOAD4; 

bitField=bltFieldStorer4l: 
goto returnPoint4; 

/* the c<x!c ihcn continues with hcgin6 up to Ix-gin tf>.'rhc p^tttern the 
code b* folkiwing after each “begin’ should Ixr clear now? 

The Ni/c of the code gTxws with n^2, and txcomes e^iniplcicly 
dominaLcd by SetTJitO.This is tiennitely the phicc for turtber 
optimi/;uion! Several things spring lo nnimt 

At the mometii I suspi'ti the SelUitO maenjs are executed in strict cirdet 
since the lenipbitFiekl register is always Ix-ing motlhietl. Hy using a 
number of dilTeretU registers that are wriuen to, it might be possible to 
allow a niueJi greater degree of iiisirucUou interleaving, which looks as il 
it eouUl at least dtuihle die specs:! if done clevcrlyS^ 

lire other place for improvement is the the ■if(tempBitF*cld=='n' 
lines (st-e note in introduction). 

V 

begln6: 

tfimpBitField-blankSicFleld: 
sotForbiddnnfi: 

flfsm I HadRItCRPOO) 

HiidBitCRPOl) 

llijdBll(RF02) 

HadMt(KP03) 

HadBitCRPOA) 

HadBlt(RP05) 

SetBit(RPOS,RPO!,RPOO) 

Sf!rBi r(RP05»RP02.RP01) 

Sc I Bit CRP0!i.RP0T,RP02) 

SctBltCRP0!?.RP04.RP03) 

SetBlt(RP05.RF03.RPU4} 1 
if CtempBitFleid*^-1) 
goto endS®tForbidden6 3 
asTO j SotBit(RP04,RP0a.RP00) 

Sot Bit( RP04 * RP03 * RPO1) 

BctBh (RP04,RP04,RP0P,) 

SclBllCKP04*RP0!j.r<P03) 

SetBit(RP03.RP03 * RPOO) I 
ifCtenipBitFieJd^-l) 
goto ®ndSetForbidden6: 
asm I SetBitCRPO3,RP04.RP0l) 

SetBit(HPD3.RPOS.RP02) 

Set Bit (RPO2.RPO4*RP00) 

Set Hi L (RP02, KPO:>»RPO1) 

SetBit(RPOl.RPOb.RPOO} I 

otidSotForbldden6: 
if{t6mpBltField“"l) 
goto returnPoint5; 
b i t FI c T fl^rcinpR i t F t el d ; 
blLFlcldStoro[6]=blLFleld; 


for Chi tWnQi=0 :bitKuin<n:) 

I 

i f ( (b i t F i cl d h Cknne«b J tNum)) —0) 

[ 

//Rc m PcisStf ire I m w I=bit Nu m; 

ST0RE6: 

if (n=7) //record layout! 

I 

ifCRP0l>n/2 && RP00“n/a> 
return count: 

epiiLasArrays [count "u] I<<RP00) : 

costasArray®[count *n+l]”(1<<RPG1): 
costasArrays [count "n+2j = ( l<<KPt)2) r 
costasAtrays[count"n+3]*[l<<RPG3 )3 
costasArrays [count *n+4]-*U<<RP04) : 
costasArrays[count“n15]"CI<<RP05): 
co^tanArray,^! [count "nl fj] = ( I <<RP0fj) : 
count++: 

costasArrays [couuL ‘ uj “(b4>>l<P00) t 
costasArrays [count *n+lJ = (64>>RPt3!) 
costasArrays [count*n+2j "^[64>>RP02i 
costasArrays [count*n+3j ‘^C64»RP03) 
costasArrays[count"n+4]“C64>>RP04) 
costas Arrays[count"ni5 ] “(64>>RP05) 
eostasArrnyn [count, "n+fi] t64>>RF06) 
eoiml++i 
goto doRcturnb: 

I 

goto be^iu ?i 

[ 

rntiirnPoint.fl: 
b 11 Mum44-; 

I 

doReturnb: 

// bitFSfum=Kow|4jjiSUjre| itjw] 3 
LOADS: 

bitFlel d=bJ tFicldStorc151: 
goto teturnPolfitS : 

beglti/ 3 

terapBltField-blankBiLFleld: 
setForbidden7: 

asm t HadBit(RPDO> 

RadBitCRPOI) 

PadBiT(RP02) 

HadBlt CRP03) 

JladHit (RPt)4) 

HadBitCRFOS) 

HadBxtCRPOh) 

SetBitCRP06»RP01.RPOO) 

.^etBit (RP06 . RP02 . RPOI) 

Scr Bf t (RPOfKRPOl ,RP02) 

SeiHlt(RP06,KP04.RP03) 

SetBit(HFOb.RPOS,RP04) I 
it (teinpBitFieid™ 1) 
goto endSetForbidden/; 
asm r SetBit(RP06.RP06.RP05) 

SatBit fRPD5.HPO2.RPD0) 

SfJ Hl t (RPfri.RPOl.RPDI) 

Sc(Pit [RPnS.RPD4.RF02) 

SeUUl (HP0S.KPt)S JfP03) 1 
if (t empBltFi eld= 1) 
goto endlietForbidden /3 
asm I SetBlt(RP0S,RP06.RP04) 

SetBit fKP04.HP03.RPOO) 

SotR1t(RP04,RP04.RPO1) 

ScT HI I(RP04.RrOS.RP02) 

StHBi L (RP04 . RP06. RP03) I 
It (teiiipBitFleld= 1) 
goto endSetForbiddeu/: 
asm I SetBit{RP03.RPO4.RPQO) 

SatBit(RP03.RPOS.RPOt) 

Sot Bit(RPO 3,RP06.RPD2) 

SetRit(RP02.RP0S.RPOO) 
SelHil(Rf02,RP06.KPOt) 

BetBit (RFO1, KF05. JlFUO) 1 

endSetForbidden?: 

If CtciiipBitField-=^' 1) 
goto rc.turnPointb3 
b 1 1 Flold'^tctnpRl tF] cld: 
bit Field St ore I/]=b lt F1 eld: 
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for fhitNiijn-f) :bl LMiimCn t ) 

I 

1 r (C b 1L b' l «i 1 d fie (kOne< <bl t tun) ) =0) 

{ 

//KowH>s$t(jn:|niw|==bttNiuti; 

STORE?: 

ifCTi=™S) //rtft’oni hiytJiit! 

I 

ir(RP00>=ti/2) 
return count; 

cost^sArrays [count *111 —Cl; 
co^taaArraya[count*n ^1l-Cl<^RP0l); 
costasArrayst f count'nil] "C : 

costasAr rayfj [rQum-'n+ll ”( K<RP0^) ; 
cofifanArrayn ^n+A] ^(1 C<RP04) : 

roGt anArriiy s [count = ( 1'C<!KPU1 s3 ; 

coa tasArruya tcoun t *n+6} = (1C<RPQ&): 
costasArrays [count•n+7j-Ct«RP07) ; 
count-H-; 

costastArrays [count‘n 1 = ( 128»RP00) : 
coeftasAr rays [ count * n+11 ^ 11 2B> >R HO 1) 
costasArrays [cntmt •n+2] "(1 28»RP02) 
coatanAr rayn [count *i(+3] = ( 1 2S>>JU'03) 
coal fiaAt ruy u [coun t *n+4] = Cl2B>>RP04) 
coatatjAr ruya [count *n+3j -(128»RP05) 
c ostaaAr ray a [count * n+6 ] - (12 8»RP06) 
coatasAr rays[count * n+ 7}"C128> >RP0 7) 
count++; 
j^oto doReturo?; 

I 

goto bagInS; 

1 

reLurnPolfit / 

bitNunrH-; 

i 

doReturn?; 

// bitNuiii^R 4 ywtHMStorc(rt»w|; 

LOADf); 

bit.F]ald^b1tF1o1dSLoro[63 ; 
goto rclurriPolntb; 

beftinB: 

tempBitFiald-biankBitFleid; 
satForblddenB: 

asm I HadBit{RPQO) 

HadBJtCRPBI) 

HaclBl l (RP02) 

[kKlHiL(KP03) 

lladBlt^RPDA) 

aadiiit(RP05) 

HadBlttRPOa) 

HadBltfRPO?) 

SatBir(RPO7,R?0l*RP003 
SatBLt CRP07*RP02,RP01) 
fiotBil CRP0/,RP03.RFD2) 
SelHiL(RP0/,RP04.RP03) 

Settiit(RP07.RP05.RP04) I 
if (teaipBltFieid“*-1) 
goto endSetPorbiddenB: 
asm I SetS1r(RP07*RPnA.RP03j 
SRt.Klt (RPO? »RP07 ,RP06) 

Sol HU (RPO6J4PO2.RPO0) 

Sc L B11C HPOb , R PO 3 , RP 01) 
SeLBitCRP06,RP04,RP02) t 
1 £ (tempBitField—-1) 
goto endSetForbiddanB; 
asm I SetBit(RP06.RPa5,RP033 
SetBit (HPOfi. RPOb, RP04) 

Sor.B 11 {RPOb, RP07 , RPO!} > 

SFjtB 11 {RP05 . RP03 > RPOD > 

S r L H i L (RPO b , R P04 »RP D1) [ 

If (tetiipBitFieid=-l) 
goto endSetForbiddcnS; 
asm \ SetBitCRP05.RP05.RP02) 

SetBit(RP05.RP06,RP03) 

SetBit(RP05.RP07.RPD4) 
Set.Blt(RPO4*RPO4.RP0O) 

SeLBlL(RP04.RP05.RFOl) 1 
I r{ LcntpBltField= 1) 
goto endSetForbiddenB: 
asm * SetBit(RP04.RP06,RP02) 


SetBit(RP04.RP07,RP03) 

SetBitCRP03,RP05/RPOO) 

Set Bit (RPO 3 . RP Of). KPO1) 1 

if (tetnpRitFleld” 1) 
goto cndScLForbiddetiB: 
asm I SeLBit{RF03*KP0/.RP02) 

SetBit CRP02.RP06.EPOC) 

SetBltCRP02.RPO?.RPOl) 
SetBitCRPOI.RPD7.RPOO) 1 

endSetForhiddenB: 

1 f(tempB^T.F 1 eTd’” t) 
goto rcLumPoiti t / ; 
bltField^tempBitFieid; 
bltFieldStore [8 J =bitFiei<i: 

for CbltNum="0;bitNum<n:) 

i 

if ((hltField^CkOnn<<hUNum))—0) 

I 

//Row Pf isSf orcj row |=bil Nnm; 

SrOHKB: 

it Cn^9) //icconJ Liyoui! 

t 

lfCRP0l>n/2 AA RPOO^n/2) 
return count: 

couiasArr ays [coimi 1<<RP00) : 

costauArrays[count*n+lj“(1<<RF01); 
coatasArrays [count *n+2j”( 1«RP02) : 
costasArrays [count*n+3 j •"( 1<<RPD3) : 
costasArrays [count*nt4l“( l<<RP0''j) : 
CoatasArraya fcount*ni 5i**( i <<RPD5) : 
contasAr raya [count *n+6]*^( 1 <<RP063 : 
conranArraya [count *rH‘7]=( l^^RPO?) i 
coGLasArrayu[couni*n+S]“(1<<RPDB3 : 
counH-t-: 

costasArraya tcount *nJ**(256>>RP0D} ; 
coatasArrays [count *n+lJ-“C256»RP01) 
costasArrays [count*n12l-{256»RP02) 
CoatasArraya[count*n+3i”(256>>RP03) 
cofitasArrays [count *n+4i^{256>>RP04) 
coni as Arrays [noun I * 11 + 5 ] — (25fc>>RP05) 
co^iasArroys[couui*nt6]=^236>>HP06) 
coh-tasArrays [count *0+7J“C236>^RP07) 
costa sAr ray s[count * n+S] -{25 6> >RP08) 
count++: 
goto doReturnS; 

I 

goto bngjn9; 

J 

rcturnPoinLB: 

1 

doReturnS; 

// l?iiNiifn=R«wP(>!iStore|tTtwl: 

LOAD?: 

bitFleld-bitFieldRtore[7l i 
goto rot u rnPfi 1 ri I 7 ; 

bcgin9j 

tempBltFleld=biankBitField: 
setForbldd€n9: 

asm * HadBitCRPOO)) 
asm I HadBit(RPDl)1 
asm I HadBitCRPD2)[ 
anm I badHU(RP03)» 
asm I liadBit(KP04) J 
asm [ liadEit(HF05) 1 
asm i HadBitCRPOS)1 
asm [ HadBitCRPO?)J 
asm IHadBltCRP08)] 

asm \ SerBlt(RP0B.RP01.RPOO) [ 
asm ( ScLBltCEPOS.RP02,RPOX) I 
asm ( SetBitCRP08.HP03.RP02) I 
asm f SetBit(RP08.RP04.RP03) 1 
asm \ SetBlt(RP08.RP05.RP04) 1 
if (tempBitField“'l) 
goto endSetForbidden9: 
asm 1 SetBitCRPD 8 .RPO 6 .RPa 5 ) J 
asm I SoiRll(RPD8.RP07.RP06) [ 
asm [ Sc?lBittRP08.RP08.RP07) I 
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asm I SetBit{RPQ7.HP02.KPOO) 
asm t SetBit{R?07,E?O3,KPOl) 
if (terapBitFleld™* 1) 
goto ertdSetFfjrb iddRn9: 
asm I Set8iL(RP07.RP04.RPa?.) 
asm I StitBit(RP0/»RP05»RPQ3> 
asm ( SetBit(KFO/»RP06.RP04) 
asm I Sei:Bit(RP07.RP07 .RP053 
asm I Se’cBit(RP{>7»RPa8,RP063 
if {tampBitFleld^' 1) 
gotcj endSfltForbldden9; 
asm { SGtBItCHPa6»RP03.RPOa} 
asm I SetBiLCHP06.RPOA»RP01) 
asm f SetBitCRF06.RP05.RP02) 
asm t SetBltCRP06.RF06,RP03) 
asm ( SetBitCRP06.RP07.RP04) 
if CtempBitField—13 
goto endSetFoTbldden9: 
asm I Set.BitCRP0f3.RP08.RP05) 
asm [ SotBJtCRP05.RP04.RP00) 
asm [ SetBit(RP05.RF05.RP01) 
asm [ SetBitCRP05.RP06.RP02) 
asm i SetBitCRP05.RP07.RP03) 
if CtempBlxFieid=-lJ 
goto endSetForbiddenS; 
asm I SetBit(RP05.RP08,RP04) 
asm [ S0tBlt(FPa4.RPO5.RPOO) 
asm I SeLSii(RF04,RP06.RP0l3 
asm I SetBlt(RP04.RP0/.RP{)2) 
asm 1 SetBit(RP04,RP08.RP03) 
if C tempBitFieldl= -1) 
goto endSetForbiddenO; 
asm I SetSit(RP03.RPO6.RPOO3 
asm \ Set8lt{R?03.RP07.RPOJ) 
asm ( SetBiL(RP03,RPaS,RP02) 
asm t SetBlLCRP02.RP07.RPOO) 
asm t SetBitCHP02,RF08,RP01) 
asm f SetBitCRPOl.RPO8.RP00) 

endSetFoirbidden9: 
if C tetnpRl tPleld™-1) 
goto returnPolniSj 
bltFleid-tempBliFleld: 
bitfields tore t9|*=^bitField *. 

for (bitNum“0 i bitNtimCn: ) 


( 


If { CbitFieldSik0ne<CbltNtjm3 )=C1) 
t 


biLKunrH-; 

\ 

doRetuna9; 

// hiiN uni=RowPosSiort | row j; 

LOADS^ 

bltField“b±tFieldStoref8]; 
goto returnPoiritS; 

beglnlO; 

t empBi tFiel d=b 1 ajik-Bl t f' 1 e 1 d : 
setForbiddenlO: 

asm I HadBitCRPOO)I 
asm I HadB±t(RP01)] 
asm I HadRlt(RP02)1 
asm [ HadBit(RP033i 
asm I HadBlt{RP04) 1 
asm ( lIadB±t(RP05 ) J 
asm { HadBit{KPD6j ) 
asm i HadBit(RP073 ] 
asm f HadBitCRPOS)1 
asm (HadBltCRP09)J 

asm f SetBit(RP09.RPDl.RPQO) 
asm t SetBiLCRP09.RP02.RP01) 
asm I SetBitCRP09.RP03,RP02) 
asm ( SetBitCRF09.RP04.RP03) 
asm ( SetBlt(RP09.RP05.RP04) 
if{tempBitField-=-l) 

goto endSetForbiddenlOI 
asm { SetBitCRP09.RP06.RP05) 
asm [ SeLBit(RF09.RP07.RP06) 
asm [ SetBitCRP09.RP08.RP07) 
asm I SetBit(KP09.RP09.RP08) 
asm ( SetBit(RPO8.RP02.RPOO) 
if (tempBitField=-1) 

goto endSetForblddenlO: 
asm I SetRlt(RP0a,RP03.RP01) 
asm I SeLBiLfRP08.RP04.RP02) 
asm I SetBit(RP08.HP05.RP03) 
asm ( SetBlt(RPOS,RP06.RP043 
asm \ SetBit(KP08.RP07.RP05) 
i f (tempB itF i e Id^ -1) 

goto endSetForblddejilD; 
asm J SetBitfRP08.RP08.Rr06) 
asm 1 SetBit(RP08.RP09.RP07) 
asm I SetBit{RPD/.RP03.RP00) 
asm I SetBit{RP07.RP04.RP01) 
asm I SetBit(RPD7,RP05.RP02) 
If 


//RowlAtsStorcl row |=hilNiim; 

STORESJ 

asm 

goto endSetForbiddenlO; 

1 SetBit(RP07.RP06.RP03) } 

if C n*" 10) //record layout! 

asm 

asm 

1 

SetBit (RP07.RP07.RP04) ) 
SetBit (RPO/.RPOe.RPOS) 1 

E 

asm 

1 

SetBit(RP07.RF09.RF06) 1 

if(RP00>-n/2) 

asm 

E 

SetBit(RP06.KP04.RPOO) 1 


return rount; 

cost asAr rays [counr *ril = ( 1 <<RP003 ; 
cos Las Air rays [count * n+l] = Cl<<RP01) j 
COStasArrays[count*n+2]~(1<<RP02); 
costasArrays [count‘n+^3j = Cl<<RP03) ; 
costasArrays[count*n+4]^Cl<<RP04): 
costasArrays [count*Jit5HCl<<RP05) ; 
costasArrays [count *11 i6l^(l<<RP06) ; 
cost asArrays(count*n+7]^C1<<RP07 3 : 
cosLasArraya(count *n+8] = C1<<RPOB); 
coatasArraya [count 1<<RP09) i 

count++; 

costasArrays [count *nj *“(512>>RP00) : 
costasArrays [count^n+l]“C512»RP01) 
costasArrays [count*ni 2l = (512»RP02) 
coBtasArrays ieount*n+3l = C 512»RP03) 
costasArrays [cotirit*n+4l (5 J 2>>RP04) 
costasArrays [cotiJii*n+5] “(512>>RP05) 
costasArrays [count *n+6] = (512»RP06) 
costasArrays [ count * n+7 J ^ C 512 >>!IP07) 
costasArrays fcount*n+8]-C512>>RP0S) 
costasArrays fcount*n+91 = (512»RP09) 

couiit+4 ■ 

goto doReturn’?'! 

I 

goto beginlO: 

J 

returnPoint9; 


if CtempBit Field—* 1) 

goto eiidSetForbiddenlO: 
asm I SetBit(RP06.RP05.RP01) 
asm [ SetEIt(R?06.RP06.RPt>2) 
asm I SeLBiL(KP06.RP07,RP03) 
asm I SetBitCRP06.RP08.RP04) 
asm f SetBitCRPa6,RPa9.RF05) 
if CtempBitField^* 1} 
goto endSetForbiddenlO: 
asm I SetBit(RP05.RP05.RPOO) 
asm I SetBitfRP05,RPO6,RPOl3 
asm I $elBlLCRP05.RF07.RP023 
asm I SetBit(RF05.RP08.RP03) 
asm I SetBit{RPa5.KP09.RP04) 
i f C tenipBitField= -1) 
goto endSetForbiddenlO: 
asm E SetBitCRPO4.RPO6.RPO0) 
asm I SetBitCRF04,RP07.RPQ1) 
asm I SetRll(RP04,RP08.llP02) 
asm ( SetBitCRP04.RP09.RP03) 
asm { SetBit (RP03.KPO/.KPOO) 
If CtempBitField= -1) 

goto endSetForbiddenlO; 
asm [ SetBit(RP03.RPOB.RP01) 
asm 1 SetBitCRP03.RP09.RP02) 
asm I SetBitCRPO2.RPO8.RP00) 
asm ( SetBit(RPO2.RP09.RP0l3 
asm 1 SetBitCRP01.RP09.RPO0) 


I 

I 

] 

I 

] 


\ 

I 

I 

1 

1 


1 

» 

I 

I 

i 


I 

I 

I 

I 

I 
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endSetForbiddenlO: 
if<rfiiapBltFi€!ld“-1) 
goro retyrnPoinl9; 

bitFleic[=t^nipBitField r 
bitFieidStore[10]-bitFleldi 

for CbitNuiit=0 jbitNutn^n s) 

t 

if f {bStF!eld&CkOnc«bJ LNum})=^0) 

\ 

//RowPosStorclrow | ^bitNum; 

STGREIO; 

1 f { n=11) //rcc( jnd bvcjtJt! 

t 

if(RP0i>n/2 U RP00-*r\/3) 
return couiiL; 

cost a ^’Arrays [count ■!!] = { l<<RFaO) : 
costasArrays [count*nfl J —(1«RP01) : 
costasAtrays[count*n+2]“Cl«RP02 ): 
costasArrays [count 31" (l<<itP03) ; 

costaaArraya [count *n+^j] = Cl<^RF04i : 
coatasArraya [count, * n+5] = (1 <<^RP05) : 
costasArrays [couni *n+6] = Cl«RP063 : 
coslasArtaya[count *n+/] = (l<<RF07); 
cos taaArraya [count (iK^RPOS) t 

costaeArtays [count *n+9j“(1 ^<^RP093 I 
costas Arrays [count ^n+ 10] "Cl«RP10) ; 
count++i 

cofitasArrays[count * n] = C1024>>RPOO); 
costasArrayn [count *n-*-lJ™C 1024»RP01) ; 
costasArrays [count *n-*'2]^Cl024>>RP02) : 
CoStasArrays [count *n+3 ] —Cl024^>iiP03) ; 
CostasArrays[count*n+4j=(i024>>KPD4); 
costasAr rays [count *0+51 = (1024»RP05) ; 
costasArrays [count *nf6] = C 1024»RP06) r 
costasArrays [count •nf 7l = (X024»RP07) ; 
costaaArrays [count t024>>RP08); 
coHtasArrays [coun t *0+9]“C 1024!>>RP09 ) ; 
cosLaaArrays [count *rj-tlOl = ( 1024>>HF10) : 

COUIlt++* 

goto doReturnlOj 
goto beginll: 

[ 

returnPointlO: 
h! tWtim++: 

1 

doRcturnlO; 

// bitNiiin=RowPosStorefFow|; 

L0AD9: 

bitField'="bitFieldStore [9] : 
goto r&turnPo±nt9; 

begin 11 t 

tempRItField=blankB±tFicld; 
setForbiddetiLl? 

asm f HadBittRPDO)I 
asm [ HadBitCKPOI)[ 
asm i HadBitCRP02)[ 
asm i HadBitCRP03)[ 
ssm \ HadBlt(RP04)I 
asm { HadRJL(RPO!)) ! 
asm [ iladBlL(RP06) ) 
asm [ JladBit(RP07 3 J 
asm E HadBltCRPOS)1 
asm I HadBit(RP09)I 
asm fHadBitCRPlQ)} 

asm ( SetBitCRPlO^RPOl,RP00) \ 

asm I SetBitCHPl0,RP02.RP0X) [ 

asm f SetBit(RFlD,KP03,RPD2) } 

asm t SctBit(RF10*RP04.RP033 I 

asm [ SetBit{RP10,R?05.RP04) ) 

if (tempBitFleld=-l) goto endSetForbidrienU ; 

asm I SetBii:(RP10*RF06.RP05) I 

asm I SetBit(RF10,HP07,RP06) I 

asm [ SetBlt{RPl0.RP0B,RPD7) I 

asm I SoLBiL{RP10.RP09»RP08> I 

asm I ScLBiL[RPI0»RPlC}»RP09) I 

i£(tempSitField=“"1) goto endSetForbiddenl1: 

asm E SctBitCRP09,RF02*RP00) \ 


asm I ScLl^lL CRP09,RF03,KP01) \ 

asm I SetBit(RP09*RPD4*RP023 ! 

asm i SetBitCRP09.RP05,RP03) ] 

asm I SetBit(RP09.RP06,RP043 } 

if (tampBltField=-1) goto endSotForhiddanH ; 

asm I SetBit(RP09*RP07,RP05) I 

asm ( SetBitCRF09»RP0a.RP06) } 

asm E SetBit(RP09*RP09*RP07) } 

asm 1 SotBll(RP09,RP10,RP0S) 1 

asm I SetBit(RP08.RP03,RP003 1 

if (tempBitFieid=-1) goto endSetForbiddenl I: 

asm i SetBitCRP08,RP04,RP0l) 1 

asm I SetBit(RP08*RP05,RF023 1 

asm t SotBitfRP0S.RP06.RP03] J 

asm t SoteitfRP0S.RP07.RP04) 1 

aatii ( SetBit CRPOS.RPOS.ftPOS) 1 

i£(tcinpBitPiald=-l) goto aridSeti'orbiddenll; 

asm f SetBit(RPOS.RP09.RP06) I 

asm f SetBitCRP08,RPlO.RP07) I 

asm f SetBit(RP07.RP04.RP00) 1 

asm ( SetBit(RP07.RP05.RP01) I 

asm t SetBit(RP07.RPa6/RP0Z) J 

I f (tompB i tFi eld^* ’ 1) goto cndSoLForbiddenll ; 

asm ( S0tBil(RPO7.RFO7.RPO3] 1 

asm ( SetBitCRPOT.RF0e.RPa4) 1 

asm ( SetBitCRPO?.RP09,RP0S] 1 

asm f SetBit(HP07.RP10.RF06) I 

asm i SetBltCRPO6.RPO5.RP0O) ] 

if(tempBitField=*^1) goto endSetForbiddenl1j 

asm \ SetBlt(RPO6,RP06.RP0l) \ 

asm [ 5etBU(RP06.RP07.RP023 I 

asm i Seti51t(RP06.RP08,RF03) 1 

asm t SetBitCRP06,RP09.KP043 I 

asm ( Set5it(RF06.RFl0.RP05] ) 

if (tempBitField“-l) goto endSetForbiddenl I; 

asm I SetBitCRPO5.RPO6.KPO0] J 

asm I SetBit(RP05.RP07.RP0n 1 

asm i SetBit(KP05.RP08.RP02) I 

asm f SeLBiL(RP05,RP09,RP03] 1 

asm \ SetBitCRPOS.KP10.HPQ4) 1 

if {teinpBitField=” 1) goto endSetForbiddenl 1; 

asm i SetBit(RP04.RP07,RP00) 1 

asm i SetBit(RP04.RPae.RP01) 1 

asm i SetBlt(RP04,RP09.RP02) 1 

asm i SetBit{RP04.HP IO.RPO3) 1 

asm [ SctBlL{RPO3.RPO8*HF00) 1 

ifttempBitField=-1) goto endSetForbiddenl 1; 

asm E SetEit(RP03.RP09.RP01) } 

asm I SetBit(RP03.RPl0.RP02] i 

asm [ SetBit(RP02.RP09,RP00] 1 

asm r SetBitCRP02.RPl0.RP0l) 1 

asm t SetBitCRPOl.RPIO.HPOO) I 

endSetForbiddenl1: 
if (t empBit Field”-1) 
goto returnPointlO; 

bltFieid^tempBitField: 
bitFieidStoreIU]“bitFieId r 

forCb ltNum-0:bltNuifi<n; 3 

I 

if C CbltFleld6c(k0ne<<bitNuiii) )=0) 

E 

//RowPtosSiorelrowJ =bitN am: 

STOREll; 

Iff n“ 12) //record lav<nitt 

t 

if{RP00>=n/2] 
return count; 

costasArrays [count *n] = (l«RPQ0); 
costasArrays[count*n+l1 = C1C<RP01); 
costasArrays f count * n121^ C1< <KP0 2): 
costasArrays[count * n+3]"(!<< RPO 3): 
costasArrays [count^n+Al'^C I «RP04); 
costasArrays [count *ri+5j“(l«RP05) : 
costasArrays [count *n+6] = : 

costasArrays [count *n+7] = ( K<RP07) : 
costasArrays[count *n+8 J *( 1 < <RP08 ); 
costasArrays [count*n+9]^(l«RP093 ; 
costasArrays[count*n'lOl=Cl<<RP10]: 
costasAr rays [count *n+J 1 ] - ( K^RP 1J ) ; 
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counx-H-j 

costasArrays tcount*Ti}-C2048>>EPD0) : 
eoetasArrays fcount*n+11=(2048>>RPQi); 
costae:Arrays fcount*n+2]—(2048>>RP02) i 
COBtasArrays[coun t* n+3j = C204S^^RP03); 
cosiasAr rays [counL*fi+4]*C2048>>RP04) ; 
costasAr rays [count *n+^] = [2048>>RP0!s) ; 
coBtasArrays [count' n+6 J { 204S> >RF06) : 
costasArrays[count*n+7j^(2048>>HF07): 
coetasArrays [count*n+8]’==C2048>>RP08) : 
coBtaaArrays [eounfnt^l^C2048>>R?09) : 
cpfTtasAr rays [criunt*n+10]-{2048>>RFlO) ; 
costasArrays[count *n+l1] = (204e>>RPIt)j 
count-H-j 

]|Oto doReturnll; 

goto beginlZj 

I 

returnPolntl 1: 
b \ tNiiiii++; 

I 

doRcturnl1; 

ii bitNum=RowPtisStcHXi(t>wl; 

LOAOIC: 

bitField-bitFiaidStoreElO]^ 
goto returnPolntlO: 

begini 2 : 

I cnipBi tFid d^blankaitFicld; 

setForbiddenlZ; 

asitt I HadBlt(RFOD) } 
asm I HadBit(RFOI)» 
asm I HadBitCRP02)i 
asm I HadBlt(RP03)* 
sBm ( HadRit(RP04)J 
fisin ! HndBilCRP03) 1 
EfBin ! HadBlt{RP06) J 
astn { HadBit {RPU7) 1 
asm f HadBit(RP08)1 
asm I HadBit(RP09)f 
asm (HadBitCEPIO)I 
afjm (HadBit (RPi 1) I 

asm ( SctBil (RPH . RPOURPOO) I 

asm ( SetBit(RP11.RP02.RF01) I 

asm ( SetBit(RPll.RP03.EP02) 1 

asm I SetBitCRPll.RP04.RP03) I 

asm ( SetBltCRPll ^RPO-i .RPOA) I 

If (tempBi tField“ 13 goto endSatForbiddenT2; 

asm I SetRItCRPTl,RP06*RP053 1 

asm I SoLBliCRPU.RPO/,RF06) J 

asm 1 SetBitCRPll*RP0fl,RP07) I 

asm i SetBitCRPlKRP09,RP083 I 

asm I SetBitCRFlKRP10*RP09) I 

ifCtempBltField—-U goto endSatForbiddenl2: 

asm ( SetBitCRPlURPli *RP10) I 

asm ( SctBitCHP10.RP02,RP00) I 

anm ( SatBit(HPt0»HP03*RPOt) I 

asm I SclHiLCRP10*RP04.RP02) I 

asm I SetBitCRF10.RP0b,RP03) I 

if (tempBitFidct=-i) goto endSetForbiddenl2 ; 

asm I SetBit(RP10:RP06,RP04) I 

asm I SetSit(RP10,RP07,RP05) 1 

asm I SotSlt{RPl0*RP0S.EP06) I 

asm I SatBlt(RP10,RP09,RP07) ] 

asm \ S<3stRit(RPI0,RPJ0*RP08) 1 

If (tcmpBi tField= 1) goto endSotForbiddefil2 ; 

asm ( SetBit<HPlQ.RPll,RPOg) 1 

asm I SetBit(RPa9<RP03.RPOO) \ 

asm 1 Set8it{HP09.RP04,RP01) 1 

asm 1 SotBlt(RP09.RPB5.RP02) J 

asm I SetBlt(RPQ9.RPQ6,RP03) I 

ifftempHitFidd™ 1) goto ondSctForb idden 12 j 

asm I St?lBit(RP09,RP0/*RPO4j 1 

asm I SatBit(RF09,RFOfl,RPO53 J 

asm I S€tBit<RP09,RP09,RF06) J 

asm [ SetBlt(RF09*RP10,RP07) I 

asm I S€tBit(RF09.HFil,RF08) I 

ifCta;mp5itField^"^’‘1) goto endSetFotblddeniZ; 

asm t 8ctBltCRP0B,RF04.RP003 1 

asm i ScLBUCRP08*RP05,RF0l3 1 

asm I SetBitCRP0B,RFD6,RF02) 1 

asm t SetBitCRP08*RP07.RP03} 1 


asm ( SatBltCRF08,RP08,RP04) I 

if(tempBitField-^-13 goto endSetForbiddenlZ: 

asm ( SetBit(RP08*RP09,RP05) I 

asm I SetBit CRPa8*RPiQ,RP5fj) | 

asm ( SotSIttR?Q8,RPll,RP07) | 

asm I SetBlt(R?O7,RPO5,RPO0) I 

asm ( SotBit[RPO/»RP06.RP01) 1 

1 f (tei!ipBitField=-1) goto endSetForbidd on 12 t 

asm f SetBitCRP0 7,RPD7\RP02) 1 

asm f SetBit(RP07,RFD8,RP03) I 

asm I SetBitCRP073F09.RP04) I 

asm ( SetBit(RP07,RF10,RP05) I 

asm ( SetBitfRPO? .RPU . RP06) I 

if (lciT»pBicFicld= 1) goto endSotForb iddon I 2 ; 

asm I SerBit[RPOb.RF06.RFOO) | 

asm t Set8itCRF06,RF07.KP01) I 

asm i SetBitCRP06.KP08.RP02) I 

asm ( SetBitCRP06.RP09.RP03) I 

asm ( SetBitCRP06.RP10.RP04) 1 

if C tempBitField='I ) goto endHetForbiddenl2 : 

asm I SctBTtCRP06.RPll.RP05) I 

asm ( SetBlt[RP05.RP07.HPQO) ( 

asm ( SetBit[RF0b.RF08.RF01) ) 

asm f SetBittRP03.RP09,RF02) I 

asm I SetBitCRP0S.RP10,RP03) 1 

if (tempBitField™-!) goto 6ndSetForbiddenl2 ; 

asm 1 SetBitCRPOS.RPli.RP043 1 

asm i Setfiit(RP04.RP08,RP003 1 

asm I SetBit(RP04.RP09.RP01) I 

asm ( SctfliLtRP04.RP10,RP02) 1 

asm 1 SetBlt(RP04.RFil.RF03) I 

if [tempBitFieid=-L3 goto endSetForblddeal2 ■ 

asm { SetBitCRP03.RPO9.RP00) I 

asm i SetBltCRP03.RPlO.RP01) 1 

asm i SetRitCRP03.RPII.RP02) } 

asm ( SclBUCRPaZ.RPlO.RPOO) 1 

asm I SetBitCRPOa.RPll.RPOl) I 

asm [ SetBit(RPOl.RFli,RF00) 1 

endSetFcrbiddenlZ: 
if(tempBitFiGld™“- 1} 
goto rettirnPolnt 1 1 : 

bllB*ield=LempBltField i 
bitFieldStore[iZj“bitFieid: 

for CbitNum=0;bitNum<n:) 

1 

if((bitFie1db(k0nG«bltHym))”0) 

t 

//RowPosStorc-1 row l^bir Niim; 

S'i‘OREl2; 

if C n“l 3 ) //rcconJ luvoul! 

I 

ifCRP01>n/2 RPOO“n/2) 
return count; 

coetasArrays [cotmt *nl^{ K<RP00} : 
costasAr rays[count * n+1]”C1<<RP01)i 
costasArrays [count ii 1 + 2 ] = C H<RP02) : 
costasArrays[count*n+3J"(1<<HP0J); 
costae Arrays Icount *n+4 J '*C1<<RF04) : 
coetasArraysIcount“n+5]-CI<<RP05): 
costa sAr ray e f count * n < 6 j C1 < <RP06 ) \ 

CORtasArrays[count“n+7]-Cl<<RP07): 
costasAr rays [coynt "n+Rl I <<RP0a) : 
costa^sArrays [count *n+9j^( I «RP09) i 
costasArrays[count *n+lO]-(l<<HPr0)i 
costasArraysicount*n+11 j = tl<<RPil) : 
costasArrays[count^n+i2j-tI<<RPl2)^ 
counts F I 

costasArrays fcoiint*nl“(4096>>RP00) : 
costasArrays[count*n+1]—(4096>>RPO1): 
costasArrays [count *n+2i -{4096»RP02) ; 
costasArrays [count * ti+3 ] “( 4096> >RF0 3) : 
costasArrays[count'n+4j={4096>>kP04): 
costasArrays[count*n+5]—(4096>>RP05): 
costaEArrays [count * n+b] =^{4096>>RP06) : 
c osta sAr rays[c ount * nI 71 —( 4096 > >RP0 7): 
costasArrays[count*n+Rl“C4096>>RP08): 
coslasArrays[count*0+9]-(4096>>RP09); 
costasArrays[count*n+10]=(4096>>RP10)i 
costasArrays[count*n+1l]=(40g6>>HFli )i 
costasArrays[count*n+12]-(4096>>RP12 )[ 
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counl;++ i 

goto doUetutnl2; 

I 

goxo beglnll: 

1 

t eturnPolnt12: 

blt.Nutt' • : 

I 

doRcturn(2: 

// bitNtiinss:R<nvl\MSci>n.’|n>tv): 

LOADll; 

bitFieid“bltfi«ldStore(111: 
goto returnPointl1; 

boginl3: 

l ompB t tF1Hld”blankBit FieId: 

setFoiblddenl3: 

asm ( lJadaU(RPQO}l 

asm ( HadBii(RPO1)I 

asm < HadBlt(KPU2}I 

asm I HadBit(RP03)I 

asm I HadBit(RP04}I 

asm I HadBit<RP05)I 

aam I HadBit(RP06)I 

asm ( HadRit(RP07)I 

asm I UadBil<RP08)I 

asm I HadUlt(RP09) I 

asm I HadBitlRPlO)I 

asm I HadBltlRPlDI 

asm I HadBit(RP12) I 

asm I SatBlt(RP12.RP01.KP00) ) 

asm I S«rBlt(8P12.RP02.RP01) I 

asm I SctRlr(RP12.RP03.RP02) 1 

asm I SelBll (RPI2.HP0/I.RP03) 1 

asm I SetBit(RP12.RP05.RP04) 1 

if(tempBltPield=-1) goio endS«*tForbiddenl3: 

asm ( SetBlt(RP12,RP06.«P05) I 

asm t SetBlt(RP12.RP07.KP06) I 

asm t SetBtt(RP12.RP08.RPa7l I 

asm t SetBlt(RP12.RP09.RP08) I 

asm I SelBlt(RPI2.RP10,RP09) I 

it(tempBitk'ii»ld=” 1) goto endSetForbiddenl'J; 

asm I SetBlt(RP12.RPI1.RPIO) I 

asm I SetBlt(RP12.RP12.RPII) I 

asm I SetBlt(RPU.KP02,KP00) ) 

asm I S«tBlt(RPU .RP03.RP01) 1 

asm I SetBit(RPn,RP04.RP02) I 

if (tempBi tFleld”'!) goto endSetForbidden 13: 

asm I Set»il(RPII.RPOI.RPOS) I 

asm I SatDit(KH1I.RP06.RP04) I 

asm I SetBit{HPlJ.RP07.RP05) I 

asm I SetBit(RPll.RP08.RP06) 1 

asm I SetBit(RPU.RP09,KP07) I 

If<tHmpBitField“-1) goto endSclForbtddenlS: 

asm ( SetB1t(RPU.RP10.RP08) J 

asm 1 SolRM (RPI 1 .RPU.RP09) I 

asm 1 SetHit(RPI1.RPI2.RP10) I 

asm I SetBit<RP10.RP03.RP00) 1 

asm I SetBit(RP10.RP04.RP0l) 1 

if(tempBltField“-1) goto ondSetForbiddenlS: 

asm I SetBit(RP10.RP05.RPD2) ) 

asm { SfitBit(RP10.RP06.RP03j I 

asm 1 SetBlt(RP10.RP07.RP04) I 

asm i SelHIl{RPIQ.RP08,RP05) I 

asm I SetBil{RP10.RP09.RP06) 1 

if(tempflltPield’— U goto endSetForbiddenl3; 

asm 1 SetBit(RPl0.KPa0,RP07) t 

asm ( SetBit(RP10.RPU.KP08) I 

asm I SetBit(RP10.RP12.RPO9) I 

asm 1 SetBit(RPO9.RP04.RP0O) I 

asm I SetRit<RP09.RP05.RP01) I 

i£(temp8ilFIeld“'l) goto endSetForbiddeiil3: 

asm I Setmi(HP09.BP06.RP02) I 

asm I SetBit(RP09.HP07.RP03) t 

asm I SetBit(RP09,RP08.RP04) I 

asm I SetBit(BP09.RP09.RP05) 1 

asm I Bf>tBlt(RP09.RP10.RP06} t 

ir(lpmpRlTFleld”-i) goto endSetForbiddeiil3: 

asm ( Seinit{RP09.RPll.RP07) 1 

asm I SetBll{RP09.RPI2.RP08) I 

asm ( S«tBit(RP08.BP05.RP00) 1 

asm I SetBit(RP08.RP06.RP0I) 1 

asm ( SetBit(RP08.RP07.RP02) 1 


if(tempiJitField"”-1) goto endSetForbiddenl3: 

asm I SetBil(RP08.RP08.RP03) 1 

asm I SetBit(RP08.RP09.RP04} J 

asm I SetBit(RP<J8.RP10.RP05) 1 

asm I SetBit{RP08.RPal.RP06) 1 

asm I SetBit{RP08.RP12.RP07) 1 

if{teropRirField=-I) goto endSett‘orbiddcnl3: 

asm ( SetBit(RP07.RP06.RP0O) I 

asm t SBl8it(RP07,RP07.RP01) I 

asm I SetHit(KP0?,RP08,RP0?.) I 

asm : SetBit(RP07.RP09.RP03) 1 

asm I SetBit(RP07.RP10.RP04) 1 

If(rompBitPieid—*'J) goto eridSelForbldd«nl3: 

asm I SftBitCRPOT.RPll.RPOS) I 

asm I SelRlt{RP{)7.RP12.RP06) I 

asm I SolBlItRP06.RP07.RPOO) I 

asm I SetBluCRPOb.RPOB.RPOl) I 

asm I SetBittRP06,RP09.RP02) I 

If(tempBitField-™-1) goto ondSatFotbiddenlS: 

asm I SetBit(RP06.RP10.KP03) I 

osm ( SetBit(RP06.RPll.RP04) I 

asm I SotBtr(RP06,RP12,RP05) I 

asm ( SetBIt(RPO5,RPO8,RP00> 1 

asm I SelBlL(RPO';,RP09,RP01) I 

if lt«nipBltfield= O goto endSetForbiddenl3: 

asm t SetBit(RP0f>.RP10.RP02) 1 

asm I SetBlt(RP05,RPn,RP03) 1 

asm I SetBit(RP05.RP12.KP04) I 

asm I SetBit(RP04.RP09.RP00) t 

asm I SfitBit(RP04.RP10.RP01) t 

asm I S<>LHit(RP04.RPll.RP02) I 

if(tempBitField I) goto endSetForbidd«nl3; 

asm I SetBit(RP04.RP(2.RP03) ) 
asm I SetDit(RPa3.Rl'10.RP00) I 
asm I SetBit(RP03.RPll.KP0l) ) 
asm I SetBit(RP03.RP12.RP02) 1 
asm ! SetBit(RP02.RPU,RP00) 1 
asm I Setfilt(RP02.RP12,RP0O I 
asm I S©lftlt(RP01.RP12,RPOO) I 

end SetFo rbiddenl3: 

If(terapBitFieid—^-1) 
goto returnPoint12: 

bitJJ’lt'td~tompBltField: 
bitFleldSloro[13]“bItField: 

for (bitNunfO: bitNuiD<ii:) 
t 

if ((bitFieldfi(kOne«bitNum))—0) 

I 

//RowilKiScorcl n)w|=bitNuiii; 

ST0REI3: 

lf(n—14) //record laiajul! 

I 

if(RPOO>-n/2) 
return count: 

costasAr rays [count ’n) “ (1«RP00): 
C0BtaBArrays[count*n+lJ=*(l«RP01): 
costasArrays[count*n+2l"(lC<RPD2); 
costasArcays[count•n+3t”(l<<RP03): 
costasArrays [coutil *ri+4]”( 1 f<RP04) ; 
costasArrays[count‘n+5]”(1<<RP05): 
costasArrays[count’n+6]“(1<<RP06): 
costasArrays [count•n+/]“(l«RP07); 
costasArrays[count*n+8]*(1<<RP08): 
costasArrays[count*n+9l"“(l«RP09): 
costasArrays[count*nl10l“(l<^RP10): 
costasArrays[count*n+11)=(l^^RPl1): 
costasArrays[coun t * n+12l“(1<<RP12): 
costasArrays[count *0+13]”(1<<RP13): 
counttf; 

costasArrays[count'nj“(8192>>RP00)j 
costasArrays[count*n+lJ“[8192>>RP0l); 
costasArrays(coiint’nl2]“(8192>2RP02): 
costasArrays[count*nt3l=(81922>RP03): 
costasArrays[count'n+4l”(8l922>RP04); 
costasArrays[count *n+5]™[81922>RP05): 
costasArrays [count*ti+6]**(8l92»RP06) : 
costasArrays [count’n+7] = (8192»RP07) ; 
costasArrays[count*n+8j“(8192>>RP08): 


MAKCII 2000 • MAfTECH 


PBOGRAMMKH’S OlAIJFNr.E 


85 










COStasArcayB[counfii+ 9 ]”( 8192 >>RP 09 ): 
costasArrayn [count •n+ 10 ]=( 8192 »RP 10 ) 
costasArrays [count*n+ll]“( 8192 »RPl 1 ) 
cos t as A r rays [ count •«+ 12 ]“( 8192 »RPl 2 ) 
costasAcrays lcount*n+ 13 l=( 8192 »RP 13 ) 
count++: 

goto doReturnl3; 

( 

goto beginlA; 

1 

teturnPointl3: 

bltHum*+: 

I 

doReturnl3: 


// bitNuiii=IU>wP(MScuteIniw]; 

LOAD12; 

bitFieid^bltPieldStoreCl 2 ]: 


goto 

returnPoint1 2 ; 

begin 14: 

tP-tnpBl tField=blankBitF±eld: 
cot ForbiddenH: 

asm 1 

1 lladBitCRPOOU 

fisin 1 

1 KadBitCRPOUt 

1 

1 HadBlt(RP02)) 

asm 1 

[ HadBit(RP03)) 

asm 1 

1 HadBU(RP04)l 

asm 1 

I HadBU(RP05)I 

asm 1 

i iladBlt(RP06)l 

asm 1 

1 lladBit(KP07) I 

asm 1 

[ HadBit(RP08)l 

asm ! 

1 HadBit(RP09)l 

asm 1 

1 HadBltCRPIO)) 

asm 1 

1 HadBIt CRPll)] 

asm 1 

1 HadBItCKP12)1 

asm 1 

1 HadBitCKPn)) 

acm 

I SetBltCRP13.RP01,RP00> 

eism 

t SelBitCRP13,RP02.RP0U 

asm 

I SatBitCRP13.RP03.RP02) 

asm i 

1 SetBitCRP13.HP04.HP03) 

asm 

1 SetRUCRP13.RP05.RP04) 


if(tetnpRllt'ield=*l) goto endSetKorbIddetil4: 

asm I SetBit(RP13.RP06.RP0'3) ) 

asm 1 SetBit(RP13.RP07.RP06) I 

asm ( SetBitCRP13.RP08.RP07) I 

asm t SetBit(RPI3.RP09.RP08) I 

asm t SetBitCRPn.RPr0.RP09) I 

ifCteinpBitFleld“-1) goto endSetPorbiddenlA: 

asm t Seiait(RP13.RPIl.RP10) ) 

asm 1 SetBltCRP13.RP12.RPll) ) 

asm I Set6itCRP13.RP13.RPI2) | 

asm I SetBit(RP12.RP02.RP00) I 

asm I SetBltCRPI2.RP03.RP01) I 

ifCtempBitFreld” 1) goto endSetForbidden)4: 

asm { SetRI((RP12.KP04.RP02) I 

asm I SeiBitCRP12.RP05.RP03) 1 

asm ) SetBitCRP12.RP06,aP04) J 

asm I SetBitCRPl2.RP07.RPO5) I 

usm 1 SetBitCRP12,RP08,RP06) I 

if CtempBltField“-1) goto endSetForbiddenlA: 

asm ( SetBit(RPt2,RP09,RP07) 1 

asm I SetBltCRP12.RP10,RP08) ) 

asm I SetBUCRP12.RPll.RP09) I 

asm I SetBitCRP12.RP12,RP10) 1 

asm I SetBitCRP12.RP13.RPll) | 

1 FCtetiiv8itField“-l) goto endSctForbiddenl4; 

asm 1 SetBitCRPll.HPO3.RP00) I 

asm t SetBltCRPII.RP04.RP01) I 

asm I SetBltCRPI l.RP0b.RP02) f 

asm I SetBll(RPll,RP06,RP03) I 

asm I SetBlt(KPll.RP07.RP04) ) 

ifCteropBl iField=-1) goto endSe.tForblddenl4; 

asm I SetBltCRPll.RP0S.RP05) I 

asm I SetBitCRPll.RP09.RP06) ) 

asm I SetBitCRPIl.RPIO.RPO/) I 

asm I SetBitCRPIl.RPli.KFOS) ) 

asm I .SetHUCRPll.KP12.RP09) I 

if CtempBI tFleld“-l) goto endSetForb1ddenl4; 

asm ( SetBitCRPll.RP13.RP10) ] 

asm { SelBitCRP10.RP04.RPOO) 1 

asm ( SetBitCRP10.RP05.RP01) 1 

asm t SetBltCRP10,RP06,RP02) I 


asm I SetBitCRP10.RP07.RP03) ) 

if CtempBitField”-1) goto eiidSetForbiddenl4: 

asm ( SetBit(RP10.RP08.RP04) I 

asm I SetBitCRP10.RP09.RP05) ) 

asm I SetBltCRF10.RP10.RP06) 1 

a.'.ro I SctBitCRPlO.RPll.RPO?) 1 

asm ( Set6it(RP10.RP12.RP08) I 

if CtempBitField—1) goto endSctForbiddenl4; 

asm ( SetBitCRP10.RP13.RP09) ) 

asm [ SetBitCRF09.RP05.RP00) 1 

asm I SetBitCRP09.RP06.RP01) 1 

asm I SetBltCRP09,RP0/.KPO2) I 

asm I SetBltCRP09,RPO8,RP03) 1 

IfCtqmpBitField=—-1) goto endSetForblddenlA; 

asm ( SetBitCRP09.RP09,RP04) ) 

asm I SetBitCRPO9.RPIO.RPO5) 1 

asm I SetBitCRP09.RPlI .BP06) 1 

asm I SetBitCRP09,RPI2.RP07) 1 

asm I Set.BltCRP09.RP13,KP08) I 

ifCtempBlt.Fleld= l) goto endSetFotbldden 14: 

asm I SetBitCRP08.KP06.RPO0) I 

asm I SetBitCRP08.RP07.RP01) I 

asm I SetBitCRP08.RP08,RP02) t 

asm I SetBitCRP08.RP09.RP03) 1 

asm I SetBltCRP08.RP10.RP04) 1 

if CtempBitField— 1) goto endSetFotbiddenl4; 

asm 1 Set.BitCRP08.RPll.8P05) 1 

asm I SetBitCRP08.KP12.RP06) ) 

asm i SetflitCRP08.RP13,RP07) ) 

asm I SetBitCRP07.RPO7.RP00) ) 

asm I SetBitCRP07.RP08,RP0l) ) 

If CtempBitField—-1) goto eiidSetForbiddenl4: 

asm I SetBlt(RP07.RP09.RP02) I 

asm I Set.BltCRP07.RP10.KP03) 1 

asm I SetBitCRPO?.RPn.RP04) 1 

asm I SetBitCRP07,RP12.RP0S) 1 

asm I SetBitCRP07.RP13.RP06) 1 

if CtempBitField—1) goto endSctFocbiddenl4; 

asm I SetBitCRP06.RPO8.RP00) I 

asm 1 SetBitCRP06.RP09.HPOU I 

asm I SetRitCRP06,RP10.HP02) I 

asm I SeiBltCRP06,RPll.RP03) ) 

asm t SetBitCRP06.RP12.RP04) 1 

If CtempBitField—1) goto endSetFutbiddenl4; 

asm I SetBitCRP06.RP13.RP05) t 

asm I SetBitCRP05.RP09.RPOO) 1 

asm I SetBltCRP05.RP10.RPOU ) 

asm I SetBU(RP05.8Fll .RP02) I 

asm I SctBltCKP05.RP12.RP03) I 

If CtempBitField—■ 1) goto endSelFot'blddenl4: 

asm < Set81t(RP05.RP13.RP04) I 

asm I SetBitCRP04.RP10.RP00) I 

asm ( SetBitCRP04.RPll.RP0U I 

asm t SetBitCRP04.RP12.KP02) I 

asm t SetBltCRP04.KP13.HP03} I 

IfCtempR.ttrield=-U goto endSetForbIdden 14; 

asm I SetBitCRP03.RPll.RP00) ) 

asm ( SetBitCRP03.RP12.RP0U ) 

asm ( SetBitCRP03,RP13.RP02) 1 

asm ( SetBitCRP02.RPI2.RP00) t 

asm I SetBlt(RP02,RPj3.RP0U I 

asm I SetBltCRPOl.RP13.RP00) I 

endSelForblddenl4: 

i f C1 empBitF iei d— 1) 

goto returnPoint13: 

bitField=tempRItFlold: 
bltFieldStore[14]“bitFleld; 

for CbItNum^O;bitNum<n:) 

I 

if {Cbi tFleldS. C kOne«b 1T Num)) —0) 

I 

//R{>wPiis.Suire|n)w|=btiNuiii; 

.ST0REI4: 

! f ( n=l 5) //record layout! 

( 

ifCRP01>n/2 && RPOO—n/2) 
return count; 
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costasArrays [count•iil=(l«RPOO): 
coulasArraya [couiit*n'H] = (1«RP01): 
cotsiasArraya[count’n 12] =(1«RP02): 
costasArrays [count *n+3l = ( 1«RP03): 
costasArrays lcomil*n+A] = ( l«RP04) ; 
costasArrays [count' n+bj = (l«RP05): 
costasArrays[count*n+6j“(l<<BP06): 
cooTasArraysicount*n+7j“{l.«RP07): 
costasArrays[coimt*n+8]“(l«RP08) ; 
costasArrays[count*n<91={1<<RP09): 
costasArrays[counr*n+10]“(!«RP10) : 
costasArrays[count’n+tI]“C1<<RPl1): 
costasArrays [count * n+12] “ 11 «RP 12); 
costasArrays [count’n+l3] = U<<RP13): 

CORtasArrays[count*n+14]=(1<<RP1A); 
count+1! 

cos LasArrayn[cQunt*nl = (16384>>RPOO): 
cos LasArrayo [cnimT*n+ll “(16384>>RP01) : 
costasArray8[coiini*n+2]=( I f»384»RP02); 
costasArrays [count* 11+3] I6384»RP03); 

costasArrays[count*n+4]“(16384>>RP04): 
eoBtasArrays[count*n+5]=(16384>>RP05)s 
coBtesArrays[count*n+6]=(16384>>RPD6): 
COotasArraysfc ount •n+7i-*(I6384»RF0/)t 
costnaArrayn [cotmt*n<81“( 16384»RP08); 
costasArrays [count*n+9l=( I6384»RP09) : 
costasArrays [count “n+l 0)”( 16384»RP10) : 
costasArrays (count ‘ii+l !]=( 16384»RPI 1): 
costasArrays tcount*n+l2]=(16384>>RPI2); 
costasArrayslcount•n+13]={16384»RPI3): 
coot asAr rays(e ount•n+14j=(16384>>RPl4): 
count++! 

goto doRcturnlA: 

I 

goto beglnlS; 

I 

returnPointl4; 


b 1 TNijn!i++: 

1 

! 

doRetuttilA r 

// h i 1 N 11 ni- Ri 1 wB>sSfore 1 row 1; 

LOAD13: 

bitField-bltFieidStoreln]: 

goto 

returnPoint13; 


tempBlLFiold^blankBltField; 

eetForbidd^jrilb: 

asm \ 

I HadBit(KPOO)1 

asm 1 

1 HadBit(RPOl)1 

asm 1 

1 HadBit(RP02)1 

asm 1 

1 HadBit(RP03)1 

asm 

1 RndBit(RPD7i} 1 

asm 

1 HadRlt(RP05)1 

asm 

1 ltad81t(RP06) 1 

asm 

( HadBlt(KP07)1 

asm 

( HadBlt(RP08)1 

asm 

( HadBlt(RP09)1 

asm 

I HadBit(RPl0)l 

aam 

I HadBit(RPll}1 

a£[tii 

1 H.sdBltCRP12) 1 

a ^ ni 

( ltadHll(RPI3) 1 

asm 

i HadBlt(RPI4)1 

aatn 

i SetBit(RP14,RP0l.RPOO) 1 

asm 

( SetBit(RP14.RP02.RP01) 1 

asm 

1 SetBit(RP14.RP03,RP02) 1 

afiJTi 

1 SetBit(RP14.RP04.RP03) 1 

asm 

1 SetBit(RP14.RP05,RP04) 1 

0 goto andSetForbiddenlb 


t SetBit(RP14.RP06.RP05) 1 

asm 

( SetBit(RP14.RP07.RP06) 1 

asm 

t SetBit(KP14.RP0e,RP07) J 

asm 

t SetBit{RP14,RP09.Ri’08) 1 

asm 

t SetBit(RP14,RPIO.RP09) 1 


i f (t.ainpBitFieid“-X) goto endSetPorbiddenl 5; 

asm I Sctnit(RP14.RPn.RP10} I 

asm I SetBit(RPI4.RP12,RP11} I 

aaiii I SetBll(RP14.RP13.RPI2) 1 

asm t SetBii(RP]4.RP14.RPI3) I 

asm I SetBit(RP13,RP02.RP00) 1 

if (tempBltField^-l) goto eiidSclForblddenlS ; 

asm ( SetBit(RP13.RP03,RP0i) 1 


asm 1 SetBit(RP13.RP04.RP02) 1 

asm I SetBit(RPl3.RP05.RP03) ) 

asm I SetBit(RPl3.RP06.RP04) t 

asm I SetBit(RPl3.RP07.RP0S) I 

if (tempBiLFle1d=-1) goto endSetForbiddenlb: 

asm I SBteit(RPI3.RP08,RP06) I 

asm I SetBit(RPl3,RP09,RP07) I 

asm I SetBit(RPl3.RPlti.RPOS) I 

asm I SetBit(RP13.RPll.RP09) I 

asm t SetBit(RPl3.RPl2.RPIO) I 

If {toinpBitField=-l) goto endSetForbiddenl 5 : 

asm I SotBtt(RP13.RP13.RPU> t 

asm I SetBit(RPI3.RP14,RP12J t 

asm 1 SetBit (RPl2, Rf‘03 ,R?00) I 

asm I Setnit(RP12.KP04.RP01) I 

asm I SetBit(RP12.RPOb.RP02) I 

If(teinpBitFleld=-1) goto endSeLt'orblddenlS: 

anm I SetBit(RPl2.RP06.RP03) I 

asm I SetBit(RP12.RP07.RP04) I 

asm ( SelSit(RPI2.RP08.RP05J I 

asm I SetBit(RP12.RrO9.RP06) I 

asm I SetBit(KPl2.RPl0.RPO7) I 

if(tempBitFleld*™-1) goto endSetForblddenlS: 

asm I SetBit(RP12.RPtl.RP0e) I 

aoin I SetBit{RP12,RP12.RP09) I 

asm ( SetBit(RP12.RPl3.RP10) I 

asm t SotBit(RP12,RP14.RPll) I 

asm I SetBit(RPl1.RPO4.RP00) I 

if{teiapBitfield=“ l) goto end.SetForbiddenlS: 

asm I SetBit(KPll.RPOS.RPOr) i 

asm I SetBit(RPl1.KP06.RP02) I 

asm I SetBit(RPl1,RP07.RP03) I 

asm t SetBit(RPll.RP08.RP04) 1 

asm t SetBit(RPll.RP09.RP05) t 

if CtempHiiFlGid=-1 > goto endSetForblddenlS: 

asm 1 SetBit(RPl1.RPIO.RP06) I 

asm I SetBit(RPl1.RPl1,RP07) I 

asm I SetBit(RPl1.UP12.RP08) t 

asm 1 SetBit(RPlI.RP13.RPD9) t 

aam I SetBit(RPll.RP14.RP10) J 

ir(lenipBlt.Field=-i) goto endSetForblddoiilS: 

asm I SetBit(RPIO.RPO3.RP0O) I 

asm I SetBiL(RPIO.RPO6.RP0l) I 

asm I SetBit(RPIO.RP07.RP02) I 

asm I SetBit(RPIO.RP08.RP03) I 

asm t SetBit(RPIO.RP09.RP04) I 

if(tempBitFieid-1) goto endSelForblddenll: 

asm I SetBit(RPIO.RPIO.RP03) 1 

asm I SdtRlt(RPlO,BPll.RP06) 1 

asm I SetBit(RPl0.RP12.RP07) 1 

asm I SetBit(RPIO.RPI3,RP0e> I 

asm I SetBit(RPIO.RP14.RP09) 1 

if(tempBltPield™*-1) goto endSetForblddenlS; 

a.sm I SetBit(RP09.RP06.KP0O) I 

anm I .SetBit(RP09,RP07.RP01) I 

asm t SetBit(RP09.RP08.RP02) t 

asm I SetBit(RP09.RP09.RF03) I 

asm I SetBit(RP09.RPIO.RP04) I 

if (tempBitFieid” I) goto endSetForbiddenlS; 

asm t SetBit{RP09.RPl 1 .RPO'i) I 

asm i SetBit(RP09,KP12.RP06) 1 

.aam i SEtBlt(RP09.RPi3.KP07) 1 

usm 1 SetBit(RPO9.RP14.RPO0) t 

asm I SetRir(RPO8.RPO7.RP0O) 1 

if(tempBitFieid—^-1) goto endSetPorbiddenlb; 

asm I SetBit(RPOa.RP08.RP01) I 

asm I SetBit(RP08.RP09.RP02) I 

asm I SetBit(RPO8.RP10.RP03) I 

asm t SetBit{RP08.RP11.RP04) I 

asm I SetBit(RP08.RP12.RP03) ) 

ir(leropBitField=-1) goto endSetFotbidden 15: 

asm I SetBit(RP08.RP13.RF06) 1 

asm I SetBit(RP08.RP14.RP07) 1 

asm I SetBit(RPO7.RPO8.RPO0) 1 

asm I SetBit(RP0/,RP09.BP0l) 1 

asm I SetBit(RP07.RPIO.RP02) I 

if(tempBitField^-1) goto endSetl'orbidden15: 

asm t SetBit(RP07.RPll,RP03) I 
asm t SetBit(RP07.RP12.RP04) 1 
asm 1 SetRit(RP07.RP13.RP05) 1 
asm I SetBit(RP07,RP14,RP06) 1 
asm I SetBit{RPO6.BPO9.RP0O) I 
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if{tempBltFleld*™-1} goto endSeLforbiddenl5: 

asm I SetBit(RP06,RP10*RF0l) I 

asm I SetBltCRPD6.RPlI,RP02> ) 

asm I S«>TRit(RP0b,RP12.KP03) 1 

asm I SetRlLCRP06.RF13,RP04) I 

asm I ScLBiLCRP06,HP14.RP05) I 

if C LeiiipBitFlaid=--1) goto endSetFarb 1 ddotil t?; 

aaia I SetBit CRP05 .EPIO,RPOO} I 

asm I Se t Bit (EPOS. RPll.RPon I 

asm i SetBit (RPO'>* HP 12,RPQ25 I 

asm t SetBit^RPaS.RPia/RPOl) I 

asm I SetBlt<RP05,RP14,RP04) 1 

if CtfjmpBi t FiEfld==-1) goto endSetPorbiddan i S i 

asm I SeLBit(RP04,RP11,RF00) \ 

asm f SetBit(RP04*RP12,RP01) I 

asm I S6?tBit(RP04,RPl3.RP02) ] 

asm I SetBitCRP04,EPl4,RP03) ] 

asm I SetBlt(RPQ3,RFI2,RP00) I 

it(tempBitFJald*™ 1) goto endSetForbiddeniS; 

asm I SfttRitCRP03.RFn,KP01) 1 

asm I SetRlt (ltP03.RP14.RP02) I 

asm I SetBit(RFaZ.RP13.RP00) 1 

asm { SetBitCRP02.RP14.RP01) I 

asm i SetBit<RPO|,RP14.RPOO) I 

endSetForbldderii? : 

if (tempBI tFicldl^^ 1) 
goto returnPoint14: 

h ILfieid"tempBitFleld r 
blt FiaidStore[151=bitFieJ d; 

for(bitWum^D;hITNura<n i ) 
i 

1 f C (bi iFleidli tkana«bitNvm) )=0) 

\ 

//lb I w l\ jsStorc 1 n> w I =hi t N li hi ; 

STDHElSr 

if Cri=^16) //rrcciixl lavtnit! 

( 

} rCRP00>“ii/2) 
return count: 

costasArrays[count•nl=(1<<RP00 )i 
costasArrays [coimt* 0+1 ] = (1«RP01) ; 
coataeArrayn [couTVI *ii+2]*Cl<<RF02) : 
costasArrayn [count *11+3J = (1«RP03) : 
cost asArraya [count *0+4] -{1«RP04) ; 
cos to sAr rays [count *n+5 ] ^( l«RP05) : 
cos t asArray s[count * n+6 )=(1<<RP0fi )i 
costasArrays [count*n + 71 = (1 «RPO7> r 
costasArrays[count * 11 18] = ( K<RP08j: 
costasArrayfifcoiini' *n+9i = Cl«RP0ll) : 
costasArraysfcount *n+10j = tl<<RP10): 
costa fiA r ray s [ coun t ‘ n+11J ^ (1 < <RP 11): 
cost asArrays[count‘n+l2]-Cl<<RP12): 
costasArruys[count'n+13]^Cl<<RP13): 
costasArrays [count “n+i4]^CK<R?1 4) : 
costasArraye[count *n4 15 ]=(\ <CRP1 5); 
count++: 

coetasArrays[count^n]=(32/ba>>RPOO) : 
costas Arrays [counL'nt^l] = C32768>>RP01) ; 
costanArrays[count'n+2j={3276a>>RPa2l: 
rostasArraysIcount*n+3l^(3276S>>RPD3 ); 
cos 1 asArraye [count ‘fi+4] “(32768>>RP04) : 
costasArrays[count*n+5i^(32768>>RP05): 
costasAcrays [count*n+6! = C3276B»HP06): 
costasArrays fcotinr‘n+7]^(32/68»RP07) : 
costasArraysicouiiL ‘n+B]“(32768>>RP0S) ; 
CostasAr rays [count ‘n+9j =^(3276e>>RP09) : 
coatasAr rays [count * n+l 0 J -- (327 68»RP 10): 
cosiasArcays [count *n+Il]“C32768»RP! 1) : 
cosLasArrays [count *n+i2l^C32768»EP12> r 
costasArrays [count'n+l 1] = C32768»HF13) r 
costasArrays [count n+14J =(32 76B»RF14) : 
costanArrayn [count‘ti+i3]=(32768»RP15) ; 
counrf+; 

goto ftoRot urnlb: 

I 

goto beginlB: 


r^^TUrnPolntl3; 

bUNum+-t; 

* 

doEetumlS: 

// hitNum=RnwPti!^t«rc|rit^wf: 

LOAD14: 

bltField=bitFieldSlore[l4ji 
g.oto rcturnPoliitl4: 

beg I ti 1 6: 

ictiipBitFiGld=blankBitField; 

setPorbiddenlb: 

asm ( KadBitCRPDO)J 

asm t HadBltCRPOl)I 

asm I HadRI( fRP02)I 

asm ( HadBlrCRPDl)I 

anm \ HadRltCRPa4}I 

asm I lladBlt (RF05) I 

asm r HadBitCRP06)I 

asm I HadBit CRP07)I 

asm I HadBit(RFOft)} 

asm I HadBit{RP09)] 

asm I HadBit{RP10)J 

asm I HadBit CRPll)] 

asm [ HadBit(RPl2)1 

asm [ HadBit(RPl3 )\ 

asm I HadBit(RP14)I 

asm I HadBit(RPl5)f 

asm I SetBitCRPiri.BPOl.HPOOj j 

asm I SetBit(RP15.RP02.RP01j I 

asm I SetRtl{RP15.KP03.RP023 1 

asm { SolBit(RP15.RF04.RP033 I 

asm t 8ctBit(HP15.RP0S.RP04) I 

If (tGinpBitField=-l) goto cndScl Forbiddenlb; 

asm { SetBltCRP15.KPOf>.RP05) I 

asm i SetBit (RPn.RP{17,RP06) t 

asm i SetBitCRPI5.RP0B.l<P07) [ 

asm i SetRlt (HPlb,RP0y.HP08) [ 

asm \ ScLR1lCRF15.RPI0,RP09) [ 

JrELcmpBitField=^-1) goto endSetForbiddon16: 

asm I SetBlttRPlS.RPli,RPI0) I 

asm I SetBlt<RP15.RPJ2,RPIJ) ] 

asm I SGtBlt(RP(5,RP!3,HP123 1 

asm I SetBit(RPf 5,RP14,RFn) ] 

asm I SntRJi (RP15,KPI3.HF14) ] 

If C iempBlLField= IJ goto cndSctForb 1 dden I 6; 

asm I SctBit(RPl4.RP02.RPOO) 1 

asm ( 5etBlt(RP14,RP03.RPaj) 1 

asm 1 SetBit(RPl4,RP04.RP02) | 

asm I SetBit(RPI4.RP05,RPD3) ) 

asm I SetBit (RP14.RP(16,RFQ43 ) 

if(tempBitFlold= 1 ) goto endSetForblddenlb : 

asm I Sct8it(KFl4.HP07,RP05) 1 

asm I SoLBit(RP14,RP08,RPD6) I 

asm I KetBit(RP14.RP09-RP07) 1 

asm t SeiBitCRP14.RPia,RP08) 1 

asm t SetBit (RPl4,RPn ,RP093 ) 

if EtempBitFiGld™-1) goto tmdSetForbiddenlb; 

asm I SetBlf {RPI4.RP12,RI40) 1 

asm t SptBlI{RPI4.RP13.RF113 } 

nnm \ SolBii(RP14,RP14.RP12) 1 

asm I SGtBit(RPl4.RPl5.RP13) 1 

asm [ SetBit(RP13.RP03.RP{)0) 1 

if EtampBitField^-1) goto cnd8eli'orbitidenl6 : 

asm \ SetBitCRPJ3,RP04,RP0I) [ 

asm ( SetBlt (RFn.HPa5.RP02) I 

asm [ SfitBi t (RP13.RP06,RF0:i) ] 

asm [ SolB1l(RP13*RP07.RP04) 1 

asm [ 5GtBitCRP13.RP08.RP05) 1 

if CtempBitField™* 1) goto endSot Forbiddenlb: 

asm I SetBit (RPn.RPO^^.RPOb) 1 

asm \ SetBit CRPn.RPlO.RPO?) ] 

asm I SetBtr(RPI3.RP(1 JiPOa) | 

asm \ SetRitCRP13,HF12.HP09) J 

asm I SctBit(RP13.RP13.RP10) [ 

1 r{ tGitipBitFiGid=—1) goto endSptPorbldden 16 : 

asm i SetBit (RP13,RPl4.RPn) I 

asm } SerBit(RPJ3,RPI5,RF]2) ) 

asm ( SetBlt (RPlS.RFr>4,RP00) 1 

asm I SetBitCRPI2,RP05,RF01) 1 

asm I KetBlt{RP12.RF06.KF02) ) 

I f CtcmpBltt’ield“=-1) goto endSetForbi dden16 : 
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(itiin I SetBlt(RP12.RP07.RP03) 1 

auiii ) SPtBlt(RP12.RP08.RP0<i) 1 

aem I SelHI I(RPIZ.RP09.RP05) ) 

asm t SetBli{RPlZ,RPl0.RP06) I 

asm 1 SetBlt<RPl2.RPn .RP07) I 

if(tenipBitPie-Ld=-l) golo (*ndSetFoi:biddenl6: 

asm I SetBit(RP12.RP12,KP08) 1 

a>im t SeT;Blt(RPl2.RP13.RP09) 1 

(isni t SeTBlt(RP12.RPl<i.RP10) I 

asm t SetHIt(RPI2.RP15,RPll) I 

asm I S(?IHU(RPI I ,RP05.RPOO> I 

if(tempBltPield'^ I) goto endSecFotbiddenl6: 

asm I SecBit(«Pil.8P06.RP0l) I 

asm I SetBit(RPll.RP0/.RP02) \ 

asm I S6tBit(RPll.RP08.RP03) ) 

asm I Sfit.Bit(RPll.RP09.RP04J 1 

asm 1 SiiTBlt(RPll,RP10.RP05j I 

if (tt'inpBI iFiold-^-l) goto endSetForbiddaiilB: 

asm I SeiBiltRPlt.RPJl.RPOe) I 

asm I SexUli-(RPl 1.RP12,RP07) i 

asm I SetBit(RPll,ltP13.RP0n) 1 

asm I SetBit(RPll.RP]4.HP09) t 

asm I SetBitCRPll.RPlb.HPlO) I 

1 rttC-inpBitFleld"--!) goto endSetForb I ddan I ft: 

asm I SclBIt:(RP10,RPO6.RP00) I 

asm I SalHh (RPI0.RP07.RP011 I 

asm I SetBil(RPlO.RPO8.RP02) I 

asm I SetBit(RP10,RPfl9.RP0.3) I 

asm I SetBit<RP10.«P10.RP04) 1 

if(tempBitFleld—-1) goto cndSetForbiddenlft: 

asm I SetBit(RPlO.RPn.KFO» 1 

asm t S«tBtt{RPi0.RP12.RP06) ) 

asm 1 SetBiT.(BPlO.RP13.RP07) I 

asm I SelHil(RPI0.RPI4.RP08J I 

asm I SetBlt(KP10,RPl’}.RP09) I 

if(tempBitFleld-1) gol.t) endSetForblddenlft: 

asm I SetBlt(RF09.KP07.RP0fl) 1 

asm I SetBit<RPO9.KPO8.RP0n 1 

asm I SatBit(RPO0.RPO9.RPO2) 1 

asm I Sot91t(RP09.RP10.RP03) I 

asm t St'lfJlT (R?09,RP11.RP04) I 

IfCtempBitField— I) goto endSetForbiddenift: 

asm I SetBlt(KP09.RPI2.RP05) I 

asm I SetBlt (KP09.KP13.RP()6) I 

asm I SetBltCRP09.RP14.KP0/) I 

asm I SetBit(RP09.RP15.RP08) I 

asm I SetBit(RPO0.RPO8.RPOO) I 

ir(LsmpRltFtp]d=-l) goto endSetForbiddeiltft: 

asm t SstBll(RP08.RP09.RP01) I 

asm ( SetBlt(RPOa.RPI0.RP02) t 

asm I SetBitCRPOB.RPlI,RP03) 1 

asm 1 SetBlt(RP08.RPI2.KP04) 1 

asm I SetBU{RP08,RP13.RPOb) I 

If(T.empBitFieid-1) goto endSelForblddenlft: 

asm I ScrBlt{RP08.RP14.RP06) I 

asm I SflBtl(RP08,RP15,RP07) [ 

asm I SetHll(RP07,RPO9.RPQ0) I 

asm I SetBitCRP07.RPI0,HP01) I 

asm I SetflitCRPO/.RPU.RPOZ) ) 

if{terapBitFleld= l) golo ciidSoiForbiddenlft; 

asm I .SetBlt(RP07.RP12.RP03) I 

asm I SeTRit(RP07.RP13.BP04) I 

asm I Sctait(RP07.RP14.RP05) 1 

asm I BetBil. (RPO7.RPt5.RP00) 1 

asm I SetBit(RP06.RPl0.RP00) 1 

if{tempB±tFleld= 1) goto endSetForbiddenift: 

asm I SetBlt(RP06.KP11.RP0I) I 

asm I SetBlt(RP06.RP12.RP02) 1 

asm I SetBlt(RP06,RP13.RP03) I 

asm I SclBltCRP0ft.RP14.RP04) t 

asm { SelBtl(RP06.RP15.RP05) I 

ifUempBllFleld'^-1) goto endSetForbiddenift: 

asm I SetBlt (KP05.RPH .RPOO) I 

asm I SetBlt(RP05.RP12.RP0I) 1 

asm t SetBlt(RP05.RP13.KP02) ) 

asm I .SetBlt(RP05.RP14.RP03) 1 

asm I SetBlT.(RP05.RP15.RP04) I 

if (tempBl I FlRld=-l) goto endSetForbiddenift; 

asm I SetftH (RP04.RP12.RP00) I 

asm I SetBll(RP04,RPI3.RP01) ) 

asm I SetBit(KP04,RP14.RP02) I 

asm I SetBlt(RP04.RPlb.KP03) ) 


asm 1 .SelBl! (RP03.RP13.RP00) I 

if ttempBllFicId—-1) goto etidSetForbiddeiil 6; 

asm I SetBlt(KP03.RPI4.RP01) I 

asm I SetBit{KP03,UPI5.RP02} | 

asm I SetBit{BP02.RP14.HPDO) I 

a-sm I SetBlt(RP02.RP15.KP01) I 

asm I SetBit{RP01.RP15.RP00) I 

endSeLForbIddenI ft: 

if<terapBitFlcid= 1) 
goto returnPoinilb: 

b1 1 F1e)d”tempBitFleld; 
b1 iKicldStoref 16)'"bitFleld ; 

for [bl tNuiii~0; b 1 TNiim<n:) 

I 

if {(bltFleldfc(kOiit><<bi r.Num) )=“0) 

I 

//Kowl'u.sStuivi row I=biliNuoi: 

1 r { n—! 7) //itxord layout! 

I 

if(HP0l>n/2 44 RPOO=n/2) 

return count; 

costasArcaya [count *n]*'( I <<RP00) : 
costasArrays [coun L ] “ (1 <<RPD1) : 

coarasArrays[coimt•a+2j={1<<RP02); 
coBtasArrays[count*n+3]-tl<<RP0^): 

coftranArrays[count*n+4j^tl<<i^04) : 

cuiitasArrayft [count*n+5] - ( K<RP0b) : 
coutEiaAi ray ft fcoi]nt*nt 6] *C I<^<RP063 i 
eostasArrayii [count *n+7] = (1<<RP073 : 
costasArrayu [coun L * ri+8] I 'C<RP08} ; 
costaaArrays [cQViiit'u+9Hf 1 <<RPD9) ; 
cpatasArraya [count •ri-Pl0]*( l«RPtCl) ; 
rofiraaArraya[count'o+llJ“{l<<RPi1): 
coFjtlisArraya fcount*n+izj = ( 1<CHP12) i 
coiiLutsArruyfi fcount*n^ 13 : 

coatasArrays[count•nl141—Cl<<RP14) > 
costasArraytt [coufit *n’*' I 51"(14<RP15 ) ; 
costasArrays [count ’ii+16]" C t <<hitNuiii) ; 
count-H-: 

contasArrays [count“nJ = t6lJ!>36>>RPOO) ; 
coni nfjArrays [count *n+l J“{6iJij3&»RP01): 
COES Lat^Arrayfl [count *n + 2]“C65536»RF€2); 
costabArrayR[c!otmt*nl3l = [65536»EP03) ; 
costasArrayu[couni*n+4l“f63536>>RP04): 
costasArrays [coiuit *n+5l^(6'i*5l6>>RP05) i 
costasArrays icounii*n-t6]''(6'i53fj^>RP06) i 
contanArrays [count= (65336»RP07) : 
coatanArrays [count *n+Bj =(6^b36»RP08) ; 
COSlflaArraya fcount*n+9] =’(6b336»UP09) i 
coatasArrayn [count*Ti+10l —C65536>>KP10) : 
costasArrays [ 00110 ^* 01 1 ll ■“(65536^5RPI1 j ; 
costasArrays^[count*n+17.1^(65536>>RP12) l 
costasArrays [couni * n+ i 3] *{ f>‘i53G>>RPl3) ; 
costasArrays [count ‘u+lA] ”(65536)^^RP14) : 
coKtaflAr rays t count 'n+lb] f 65536>>RP 151 I 
c o a t a a Ar r ay a [ c oiin t * n+16} ^ (6 b 5 3 6 »b 11 Hum) 
couuL+^: 

goto doHc i LI rn 1 6 ; 

1 

return count * 

I 

rcLurnPot utl6: 

bilNuirrH-; 

I 

doKeturnl6^ 

// biiNuiu=RowI4jsStoiv| fow |; 

LOADISl 

bitField*bitFieldStore[15]: 

go L o rptu rnPoint15: 
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TOOLS OF 
THE TRADE 


Hy MacTech’s Production Staff 


Large Format Printing 



The HP 25Q0CP Series Printer 


For yeani, foniiiit (e.g., poster size) priniers have been 
avjiilihle. Kecently, there have tx-xin some new clevelopmcnts in tiicse 
types of printers that wwant a kx)k if you have any lai| 5 e ftjrmjit needs. 
Tlie question iliai we asked cnirselves were ""aiu ttiese the types <rf 
printeis that we’d want to liave in a typic^al networkT To aaswer lliis, w'e 
l( K)ketl at mo sets of solutions — low ltkJ (starting at around $1700) anti 
Iiigh end, Herc^’s w^hiit we found- 

Chokjls 

Tliea- are ii wide range of clioices tliat you have when selecting 
these printers. Mna, you need to daeniiine your needs. For exjtmple, 
what types t)r media (paper) l\o ytni neeck What atom ink? (Some inks 
will fade quickly with any light ex[XKsiire). What resolution? Wliat are die 
tyiX's of ttJcjr .support that you need? 

Ifs easy to gel buried in tliese details — but ycxi will nexx! t<» 
determine them in t jrder to seleti the right printer, 

HP DRSiG.>iJrr 2500CP 

’Ihis plKHo-qualily color printer h:is chtnged our opinion of large 
fonnal printing. We Ux* tlie liF IXsignJet 2500CP out t>f tlie Ixjx, 
plugged it into a Mac G3, and it was ready to go. The IXsignJet 250(Xd^ 
and 33tX)CF series IkxIi come with Adolx FostSaipt drivers, built-in KIP, 
and a 4,3 GB hard disk ivady lo conneca to Fthemet. 

As far as nilor matching gexs, I IP s imegraltd system of printer, ink, 
ixipers mid films allows tlie 1 IP fX-signJel 25(X)CP and 3^)0CP .series 
printers to produce higli quidiiy itn^iges with millioas of colors. Automatic 
color (ijliliratitm guarantees high-qualiiy output every time, and Is 
PANTONF compatible. 

We did a lest print to dia k <Hit the .miration, and wits cxiiemcly 
plea.sed at the tmilis. tome designs cm lx hcivy in black saturation, 
lesuliing in binding on some primers, liut not liic DesignJet 2500(^1^. 'llie 
completely black and shadowtxl arcis of the print were solid and clear, 
and the midtones and liigliliglils were etjually as clear, witli Ixauliful 
exjor saturation on the glossy pajxr. 

TliLs system Is very easy to nm from your deskU))) PC. Seletling 
tlrivers, cfuinging [Minting scaings, tnlibration, and evcrytliing else 
involved in getting your design fioin your monitor to !arger-thin-!ifc% 
photo-quality print size is as easy as working your desktop ink jet printer. 
All at a aisi of about 40 cents a s(|uaa* fexjt on arated paper. 1 wcxild 
definitely recommend tlie IIP IXsignJet (2500(]F?) for anyone serious 
alxiut printing c]uaiity large format prints from iJieir desktop PC, 

Choice oi- Ink my Media/Cxist Per Copy 

^ih tlieir largex’apadty ink systems, tlie DesignJet 2500CP printer 
offers very' exsy swauiiing Ixnw'Ofn two ink sets — dye^hased for 
maxiiTium image quality, or pigment-based for enhanced figlitfasiness. A 


choice of specuil]y-devek>ped HP and 5M DesignJet media aintributes 
llirther to the output quality. 

Tfie HP DesignJet 25(X)CP piiiilcr lias a low cast-per-copyj and is 
an cxcx^ltenL addition to anyone looking for an affortiablc alternative to 
large Ibmiat printing. 

pExnms 

• True fkXklpi black and ctrior prim lesolution 

• Photo-quality output in ovct 16 millim cokm 

• AhT>-.srze color images in amund 8 niinulcs 

• Laige-capacily ink system — up to 2(XXJ sq. fi toiw^^en ink system 
cbinges 

• Auto-repienlshment ink delivery for easy replacement of ink 

• Biiilidn humidity and temperature seas<^ adjusLs drying fimt^ for best 
results 

• Auioimtic printlHfad alignment 

• Optional mke-up reel for unattended printing 

• Adoix: PcHScript 3 as standard 

• PoHttoripi drivers lor Matinitssli and Windows iiKluded 

• Keprints images quickly and easily frt>m the queue 

• AulomaLic color ailibration for consistent ie,sulLs 

• Network ready with fniili-in HP JetDirecl EfO network card for 
Ethernet 10/100 Ikcsc-JlC 

• 4.5<^B built-in hard disk 

• Print directly fnim ycxrr desktop PC 

Nm Your Fahier^s lAKtiE Format I^intfr 
It used Lo be that tht^se large ibnnat ]>rinlers were tjnly for .service 
buFKius — they w'cie ex|x.TLsivL% and tcx>k a kt of effort to use. Tliese 
Entry' level HPs can nin as little as $23(X) 17(X} C$2500 Is mote accurate 
for Mac .solutions — tolow you have $17CX)* so wc just wanicxl to keep 
it consistent.) and [>lug into your Pthemet network — in oilier wonis, 
ymi don’t need a dedicated work-staiion. If you have anything alx>ve 
"cxnisionar use needs for a laige fonnal printer, this is a printer worth 
liaving Oil your network. 

Range of Prodixt Ijnf 

lip’s smaller mrxlels (starting wath the HP DesignJet 488<:A 
printer) have Ethernet conneeiions, hut the KJP process happens in 
.software on the Mac. IIP has a full range of solutions starting at 
$1700 and going up to nearly $12,000 widi many steps in between. 
To chtxxse the model, you need to choose resolution, paper 
handling, software vs. hardware RIP, eu:., and then the HP model w'ill 
l>e obvious. See HP’s web site for more information. 
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PkKJiNG 

Tlic I IP Desigiijei 25()0CP (ilie model we revieu'etl) series luige 
fomiat printer cost approximiiiely SlOk to i)wn, 'DiiH comes fully 
fimc1ion:il and fully ajuipjx'd vviiti 

• Roll ft^l spindle, cutter knife, and hfjider 

• HP teignlei Ink System k)r iiiiaging 

• One eadi of Ijbick, cyan, magenta, and yellow 

• Two it>lls of selected medki {piper, eft:.) 

• Ink storage aintainer 

• I Jser d( joimeniaLion 

• Driven; 

• Hard disk, I IP Jetl')ireci rand for Filiernet/LocalTalk, and PexstSaipt 
drivers for Macintosh and Windows 

HP's pnxiuct line works fairly simibr to die DesignJet 25<XXP 
printer with tjuality of initput and media/ink types being the prirmiry' 
difference l>clwix‘n nuxlels, Infonnation aliout HP, arxl its pncKlucis 4:an 
Ik‘ found on the Wbrid Wkle Web at <http:/Awww,hpXOm>. 

Tiil Roiand Hi-Fi jet 

Tile I li-Pi JITT Ls a pnKikiuality printer — rlie firsi lo offer dpi 
resolution in a wkle-fomiat device. Tlie Hi-Fi JEFs printing system 
intnKliR-es a new stantljirxl for pnifesskinal dig^uii color printing, llie Hi- 
Fi JET is citliliraled to ensure accurate and consistent Cf>lor reproclutaion 
of PAN'I^ONH MATCHING S YS’I EM Oilors, when printing in Grange and 
Green. 11ie fll-Pi JHT is offers large-size [irtxifing capability of solkl 
PANTONE Qilois using IlexiidaTJiiie-liceased color technology. 

Ffaiures 

• True 1440x720 dpi high resolution printing 

• Addititinal j^rinting rntxles of 720, 3^0 and 180 dpi 

• PANTONE* Hexachrome* a>lof matc hing 

• 'Pwo interchangeable, six-color ink ,set opions for smtKXh gradations 
and vivid colors 

• CMTO, plas Orange and Green (LIV .stable pigment) 

• CMYK, light Cyan, light Magenta (dye or HV stable pigment) 

• Roland ColurChoke* driver-based KIP for Windows 
9V98/NT and Macintosh 

• Adobe PostScript* 3 

• so mh priming vvidtli willi no Icngtit limit (40'* unit available) 

• Over a dozen types of media avaikible; m^itte, gloss, film, Iracklit 
film, fine art papers and even ainvas 

• hiLS 7 set-up, as little as 30 minutes 

• Ink cartridges cm i)e ckinged mid-print job 

• Self cleaning pemianent printer heads 

ADurnoNAL Fiatures 

Tile set-iip of this laige format printer and included .siand went so 
smoodily, we didn’t need to Icxik for furiliLT dixiimentation to answer 
any c|uesiiorLs. Tlte parallel printer calile wiis included and the [namllel 
card for die Madntc^h iii^tolled quiddy as well All of the printer menus 
weie very easy to understand, aiKl provided a lR*lpful guide covering 
several popular desktop publishing prognuns. 

You cm print directly from applicatioas such as PhototShop and 
Illustmtor, or Quark Xpress. With the indudal GiloiGlioicTe^ Addxr 
Postscript^ 3 software RIP, the Ripping wail very^ quickly. The I li-Pi JEF 


indudes an automatic sIkxM cutter which w^ill cut anri st^pjmite the print 
job wlien complete. An optional lake-up roller Is available foi tolling 
extra long txiniinuous-feed prints. The ]KTimuiem print heads, ecjiripped 
with aiiLomaiic sclf-dcuning functions, produce vc*ry high quality prints, 
plioloieallstic images and snicKith ailor graclitioas. 

Rolls or .sheets of nietiia ane easily loaded and .secured with a single 
kwer. ‘fills primer oITcts a voy wide vaiiety^ of chfikx^ in printing inks, 
fomiais, sizes tind media, nuiking it extremely flexible* and aunpleiely 
adiputiile to almosi any kind of print jolt bxtding tJie medLi was a 
breeze, and the from fxind menus woe straightforwiial to tlie point, and 
exirancly heit^fuL An optkinal lake-itp roller is available for not ling extra 
long c^intinuous-feed prints. 'Ibis mak^s unalicndal [iriniiiig even easier. 

1 he Roland HlFi [Ef‘ luige fonimt printer has a seainles.s user 
imerfacc. Dsensc'an [)rint rigiit fitini their desktop publishing prognim of 
choice, without kiving to leant a new' progmm. Tht* RfPping firograin 
was auuvjrxiding and oil led itself up w hen it was neecietl. TliLs is a taie 
WysrW\"G (wliai you see is wluil ytJU get) printer. Wkir appc'-aitxl on 
the screen is what aj^peaad on tlte output mtxlia. 

AajiSSOKits 

• Power cord 

• Ink drtiin Ixxtle 

• Sheet ailter blade 

• Ri iland O ilorGioicc RIP driver 

• Quick Sum Guide 

• Usefs miinual 

• Sample File CD 

• ECP (IEEE 12 H 4 ) Parallel Qible 

• Gne ink m (Llser specified: CMYKlclm, CMYKOG, or CMYKLdm 
r>ye) 

• 3 sheets siimjilc iitedki 

• Madntosii PCI Interlice Gird (Opiiomi!) 

• Proprietary USB to Parallel C>ai)le ( 0 ])iional} 

■ Gptkinal Take Up Red for unattended printing 

’llii.s Robmd primer is a higli-end uniL It's meant for pt'Ople tkit 
either m* in ihe busines.s of creating laige formal output, or have liigli 
C]ualiiy needs (e.g., amsLs, profl^kml Wei prtxkuiion, etc...). Ycxi 
really need to hitvea high-erKl dtxlioited worksiaiion to ase die pnxluct 
well - as the lx*si way to luKik it up is direct interface vki a l<^l eatxl <ir 
I jSBrtihParaUel cuble. Hie 50** printer kis a retail piiiu of around SIHJXX) 
- so you FKilly need to have the higher end needs to justify it. But, if you 
do, yocill lie pleased with the results. 

About Roiani> IXJA Oirporation 
Roland DGA Qirponition Ls a wiKilly-ownccI sulisidiary^ of Roland 
rX} Oifporation, a manufattuier of computer-aided input and output 
devkx!s ascxl in pluXtigraplty, fine art, gniphic arts, sign making, 
engniving and 3 D mtxleling. Imrodutud m fall I 99 B, the 1 It-Pi JEF is the 
first wicle-foimat 1440 dpi Piezo inkjet, and the First device writh 
PANTONH Hcxadironic technology. 'Fhe six-color Hi-Fi JEF provides an 
cxfxinded color gamut and riuer blacks, dramalkally im[>rt 7 ving the 
realism and inierLsity^ of fulkolor repixxluctioii as well a.s offering print 
permanence of over 120 yearn when utilizing Roland pignK^nl inks. Hie 
Rokmd I E-Fi JET Ls availaNe in SO’* and 40 ” print w'klilis. For iiiofe 
informatiOT aboia Roland DGA Girporalion and die Hi-Fi JEF printers, 
visit their web site at <htlp;//www.rdandd^xorTi>. ffil 
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By Richard Ativeli ©2000 hy Metroumks, Inc., all rights reserved 


CodeWarrior Update 


Richarii Alexander rkwtd Attrell siarteU at M&trotmrks in 
J9^ tehetr he signed itp to joh? the rank^ of thix'se teba use 
CodeWarrior to write CodeWanioK If you are imemted in doing 
the same you can Tx^ach him at ratuM^IMineirou^^iiixom. 


Omi'WARRioR Rfijase 5.3 Update 

Just Iiefore the Christmas holiday, Metrowerks shipfml its 
C( Hie Warrior Release 5.3 I jxiaie. We slii(>pcd two versions: one 
iliai eonlained pre-lxiili libraries C37MB) and one tluu didni 
<2S!V1B) in order to make the downlcKid as small as ptjssible for 
ihost^ with slower connections to the Internet. 

We also updated .sonx* of our dcKunx^niaikai (6MB) htit only in 
PDl' fonnat. The updale i nr It kit's the C taaiipileis HefuRaiee, IDE 
User tiuide, MSLC Refcivncc, QLiic:kStart Pryfcssional and Tui^etin^; 
Mac OS ni;mLials. "Ihe manuals luive ixun uixiaietl la rarely to 
document tlie AltiVec siipixm in the icxils. 

Ibere is also an ujxlale to the MetroNub for java debugger 
pUigdn. 'this plug-in previously shipped on the CrxleWarrior 
Release 5 Reference Cl) in the pre-release folder. The MerroNuli 
pkig-in that tfie installer places in your Release 5 Melrowerks 
CodeWanior folder is tiot intended to debug Java anymore, 
lastead. there is a separate plug-in called the SunJavaPlugtn for 
Java taigcLs. The release rxaes with the update s^iy: 

Tilt' cmiy fcanint: thiU the old Mctnwiub/Java dL'buggtr plug-in prif)vides 
t!mt thrsi new plug-in dixsn'l is ihc ability io debug alrt^ady running Java 
etkit' wjthtnn launchtng the applkation/applci that uses it frtJin 
CtxleWarriorTn other words, with the new Sun Java tk-hugger plug-in, all 
Java debugging must originate fn>ni the IDE.Anacbbig lo an already 
running VM pftx'css b not supjxjrttd. 

If you don’t require tbi.s supfxirt tbere^s no need to install 
this extra update. Visit bttp://w^w.metn}WLTksx:om/download/ 
ftjr all the latest tools. 'Die Release 5,5 Update is [ilanned to lx* 
the last update IxTore QjdeWarrior Release 6. 

IDE 4,0.4 

With the intR>duclion of the IDE 40.4 you may liave noticed 
that there are several new plugdas in the CodeWarrior 
Plugins: Debugger: folder. Tliese art' new symbolics 
plug-ins and eac h one contains target-level symlxilks supfxni 
that was previously included in rhe IDE applicattt^n itself. Of 


interest to Mac developers are the SymSymbolics and 
JavaSymbolics plug-ias. 

We’ve made these clianges so development changes iu one 
larget don't adversely effec t otlier targel.s. We hope this will keep 
the integrated delxigger working for the Mac as we make 
recjuired changes for the other targets that we support. 

In addition to these st met oral changes, the debugger settings 
target )ireferences jianel has changed in the latest IDE, 



f igfire /, new f)ehitgger Settings Panel. 

When you open your existing projects you1l get a dialog 
confirmation that the project needs tcj be updated to die new 
settings. Wlien you give ilie OK, each target will lie updated and 
you II see a projed tnes^sage sudi lis: 

Hic data for ihe - Debugger Settings^ settings panel in target “PPC 
flehug MacOS Toolbox** of pni^'Ci “MyProjeet.mcp” has been updated 
10 the latest version. 

llie two new' options ihai require updating are Stop at 
temp breakpoint at application launch and Cache 
symbolics between runs. 

Instead of the old ^stop at main’’ debugger global settings 
preference» we now' allow‘ a Unget-speciflc preference to let die 
debugger stop at the “main" as Ixforc (default fxhavior) or ai a 
iiscT specnfletl symlTol, 
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Siin]>ly enter a function name that must l)c located in the 

symbolics (main, _smrij New Ball) and the debugger will 

launch your program and stop a I this function instead of a 
hard coded syiuixd name. Tliis is especially useful liecause 
it allows yem to start a debugging session and execute ail the 
way until you reach a location such as the function you are 
CLirrentiy debugging, then halt. 

Caching symbolics between runs is what the integrated 
debugger alw^ays used to do. Our debugger used to keep 
syniboltcs loaded until a new build was t reate<l or the project 
was closed. With our MPW coiiiiiiand line tools this posed a 
problem if the user built them, debugged, and then 
attempted to buikl with them again wathoiit closing the 
project: the tt>oLs could not write some of the output files 
since they were still being used by the debugger. 

With this (option off] symhr>iics are discarded between 
runs, wliicli frees the symbolic files so that external programs 
may modify them. The further l>enefit is that if you were to kill 
and restarr your pn^gram, symbcdics would be discarded and 
reloaded. Thai could lake some time if the SYM file is large. 

Compilers And MSL 

We shipptxi MSI. 52 anri new 2.52 compilers wath the Refeise 
5.5 lipdate. Tliere ate many new language failures available in 
the front end and impmvemenLs to the PowerPC hackend. 

Here are some front-end highlights: 

• Support for the ISO C++ section 16.8 value for the predefined 

macro “_cpliisplus”. This is set to ''1997111" to indicate 

conformance with the ISO C++ spec:ifiealion, 

• Support lor ^pragma fullpath_prepdump on I off 1 reset 
(default off). This option ran l>e used to show the full path 
of any included files in tlie comments in i\ [:jrcproccssor 
dump. When turned off, only the tilename portion of the 
paih is shown, 

• Support for ^pragma Iine_prepdump onlt)ffbeset (default 
off). This option can be used to uneommeni ihe “Hine ..." 
directives in a preprcKessor dump. This option it will also 
preserve ihe vertical line s[xicing by inserting empty line.s, 

• "+^pragma gee_ex lens ions on” now al low's automatic 
stiiici/array variables to be iniiiali^ed waih non-const values, 
such as function parameters, (non-AN SI C) 

• fl^pragma waro_no_side_effect onlolTI reset (default: off) 

• ^^pnigma wam_resu!Lnotu.sed on I off I reset (default: off) 

• _optinn{<:x>) will now rerurn ‘false’ instead of an eixor 
message if <x> is an nnlinown ofirion/Vpragma. 


• ^^pragma opi_strenglli_reduelion_siriei on I off 1 reset 
(default: off). This option can be used to disable strength 
reduction optimizations that could be unsafe because the 
induction variable has an unsigned type smaller than the 
pointer type. Previously, this option was controlled solely 
by the ANSI strict setting. 

Some PowerPC backend higlilights: 

• Su pp< >n ^pmgma funcrionji I ign 41H116132164112HI reset 
alknvs specifying of the aligntnent of a funcLitjn. 

• AltiVec constants are now^ pooled. 

• ^l^n agnia alliv'ec_vj s;n e a lion is tiow siE|>j)c>ried. it sets 
VRsave assuming ihat all AltiVec registers are in use, best 
used Willi ‘^pnjgma allivec‘_vr.save off" so only the parent 
rtJutine U|>dales the vnsavc register. 

• Addtrd 'liiachine 74(X)" directive lo inline assembler 

Mac os Support 

We re continually updating the support folders new' that we 
.ship CDs less often. W'ilh the Release 5.2 Ufxlaie we made 
several changes to MacOS Support: 

• I pdaicd Ma('Header>s so they can he c'ompiles w'ith 
ANSI tStrict ON. This usually means removing die // 

C++ style comments and replacing them with the /* C 
style comments. 

• Added a stub library for tlie PLStringJmncs that exist within 
SttiCUh. 

• Added some common Ml^W files that are not pan of 
Universal Interfaces. 

• Retilaced fp.li with the modified Pro4 versit>n thai fixed 
problems when including cmath and fp.h in the wrong order. 

As always, we wela>me your feedback on any subject. 
Contact us through our new^sgroup or .send us email directly 
using the addresses btdowc 

• Technical Support: cw_SLjppOJt@nietrowerksxom 

• Report Bugs; cw_bug@nnetrowGrks.com 

• Suggeslions: cw_suggestion@metrowerks,com 
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The MP3 Phenomenon 


li’s nearly impossible rocky ro pick up a maga7.ine or 
newspaper and avoid seein^r an ankle alK)ut MP3s. They're 
popular and surrounded by legal controversy — all the 
makings of a good media festival. And if you go to 
VersionTracker and mn a search, you'll cjuickly find out that 
the Macintosh community is no more resistant to the craze 
than anyone else^ if you didn't know this already. Mype 
a-side, this is the sort of thing which should grab a 
developers aiieniion, because ilicre's a big murkei for 
anything which plays, produces, converts, organizes, streams, 
or finds 1 VIP 3 . 5 . 

There’s a second reason for Macintosh developers to be 
excited, beyond the sheer popularity, and that's QuickTime. 
There are three things which everyone agrees that Apple 
does like no other company: interlaces, multimedia, and 
consumer excitement. There's no question tliat QuickTime is 
right at the intersection of the.se strengths (despite tlie 
qiie.stionahle de^s^gn of the Quickl’ime 4 Movie Flayer's 
inlerfacc), and their quite lucrative investment in Akamai is a 
strong statement of their commitment to be a leader in 
streaming media. 

On the other hand, Apple's direct pursuit of the MP3 
market has been weak, QuickTime isn't the best MP3 player 
around, either in terms of playback quality or feature.s 
(althougli the QuickTime 4.1 update improve.s this 
somewhatj, QuickTime doesn't do MP3 encoding tjut of the 
box, and their Movie Player doesn't receive, nor does their 
QuickTime Streaming Serv'er produce, MP3 audio streams in 
the jx)pukir SHOllTcast format. So what's going on? 

'I'here are a couple of ways to read the situation. One is 
that Apple is merely steering clear of the craze—its 
iiujmenium Ls centered in the Windows c'ommunity, [here are 
legal issues with tlie distribution of M?3s and copyriglit 
violations, and there are licensing fees required for encoders. 
While this may be irue, it\s only half of the story. Like many 
of Apple’s winning strategies, ifiis one may center around a 
.single revelation, both obvious and at the same time 
completely overlooked! the MP3 format is irrelevant. Not 
digital audio, but the idea that the consumer cares at all 
about the format of their files, or even what ^MP3" stands for. 
(For the record, it’s "MFEG-l Audio Layer 111,” not “MPEG 3," 


which dtsesn’t exist.) What ihey really care about is quality. 
The QuickTime Star Wars trailer taught us that—although it 
was available in a variety of sizes, almost eveiyone chose the 
largest, highest quality version, and you can bet that most of 
them were pulling Lhe.se multiple megabytes painfully over a 
modem. The truth is that there are better audio formats than 
MP3 out there, both in term.s of file size and sound quality. 
(This is of course subjective, but many have high praise for 
the QDcsign Music 2 fortTrai, whidi lends to be used for ihe 
audio track of high-quality QuickTime movies,) 

lliis is just speculation, of course, bui moving forw^ard 
ctmsLimers will certainly choose 10 listen 10 wlraLcver sounds 
Ix-st, and tills Ls also what artist.^ wall want to [>roduce. Does tliis 
mean that MF3 will vanish as a format? CJf course not. What it 
does mean is that consumers will Ih.^ licst .served by products 
wdiicli arc codec agnostic, and can ada[>t to play a variety of 
formats. Some of the newer MP3 hardware players are suppcised 
To support upgrades to play future formats, and of course 
(QuickTime has always supjioilcd multiple formats, because it's 
a completely modular techmdogy; third parties can easily 
produce their own compressor and decompressor components. 
In fact 1 wouldn't be surprised if some day w^e have a portable 
QuickTime player, supporting video as well as audio, 

,Sq what does this all mean to the Macintosh developer 
today? ll means that in the short term Apple has provided an 
opptjriLiniiy for developers to step in and fill a need. In the 
long term, it means that the Macintosh can take the lead in 
the digital audio arena. If you are doing anything in the MP3 
arena today, you’d be wise to use QuickTime, If you write 
your own encoder or decoder, implement it as a Quick'fime 
component, and If you license one, favor one that is 
implemented ihis way. Automatkally, you’ll lie able to 
support Ollier formats that Quickl’ime currently plays and 
formats that it wdll |:>lay tomorrow, and you 1 l be able to 
extend its capabilities without rewriting the appheation itself. 
This will give Macintosh applications (and Windows 
applicatioms w^hich embrace Apple technologies) a unique 
ability to keep apace wath changes in the indirstry. 

This numth I am going to leave you will a relatively .small 
set of links to some key resources. First off is Apple's 
Quickl'ime developer site, which contains the key resources 
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you 11 need lo integrate QuickTime into your products. 
Second is Fraunlu)ret who for i)etlLT or worse ftoJds paten Is 
to key algorithms invoived in MP3 compression, and they are 
enforcing their rights to licensing fees. They have a web page 
(or a place holder ftsr one) devoted to licensing, and youll 
want to acquaint yourself with the issues involved. On a 
positive note, they do have arguably the highesPquality 
encoder available, and their place as an originator of the 
technology shows. They also have a Few [)ages of 
introducror)' information al>r)ut the format. Next on your list 
shotikl he the MPKG Audio News, a small site which tracks 
news relevant to llic Macintosh, and lias several interesting 
articles, including an introduction to MPUG audia> a review 
of the QDesign Music codec, an encoder quality comparison, 
and an interview^ with Rafael LuchlKTt, the author of the 
historic MPecker encoder. For a look at the other formats out 
there, 1 errands Codec Central page has information on a 
variety of multimedia formats, and the Sound A pp site 
contains a page with a brief ex[danation of the many formats 
supported by this application. 

Apple - Developer ^ QuickTime 
<http://developer.apple.com/quicktime/> 

Fraunhofer IIS-A - Licensing 
<http://iisdhg.de/amm/legal/> 

Fraunhofer ilS-A - Layer-3 Info 


<htLp://www,iis,fhg,de/amm/techinf/layer3/> 

MPEG Audio News 
<http://www.raum,com/mpeg/> 

Codec Central - Info on Multimedia Codecs and Technologies 
<http://www.terranTom/CodecCentral/> 

SoundApp Formats 

<http://www-cs-students.stanford.edLi/‘-franke/SoundApp/formats.html> 

kistly, 1 would be remiss if! didn't poinl oul icccasl. It’s an 
0 ]>cn source streaming audio seiver launcheci in January' of 1999, 
and it streams MP3 audio in a format compatible with 
SHOirTcasL, the distributed streaming audio system by Ntilisfjft, 
makers of the ptJi>ular \S1nainf) iVlP3 player for Windows, Since 
A]:)ples Darwin Streaming Server is open .source as well, one 
wonders if some enlerprising developer will unify the two 
technologies, fcecast is under the GNU Public License, so there 
may lie a licensing mismatch there, but that doesn't prevent one 
from enhancing the Darwin Streaming Server to serve icecast- 
compatible sLreams without acLiially using {:ode from icecast 
(after all it was developed without the code to SIlOLTcast). 
After all, we caoT let the Linux DJs have all the fun. 

icecast 

<http://lcecast.org> 

Apple - Public Source - Darwin Streaming Server 
<http://www.publicsource.apple.eom//projects/streaming/> 
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You are here 

(parking lot 
water cooler 
conference room 
huddle room 
boss* office 
big boss' office 
latte bar) 

on your laptop, 
on your 
wireless LAN 


WaveLAN® Wireless Solutions from Lucent free 
everyone in your company from the deskbound, 
officebound network. 

With WaveLAN/IEEE Turbo 11Mb Cards, people 
can stay connected, and work productively at the 
speed of Ethernet anywhere they meet, greet or 
get inspired. Standards-based WaveLAN makes 
wireless LANs truly efficient, fast and affordable. 

See how you can boost your productivity at 
1-800-WAVELAN or www.wavelan.com. 


We make the things that 
make communications work.’** 




















Mac 


can't be wrong 




Code Warn or is the only serious choice 
for professional Marf development. 

Chances are, every Mac program you 
use was created using CodeWarrior In 
fact, more than 90% of all commercial 
Mac OS applications are built with 
CodeWarrior. 

Built with the Mao developer in mind. 

The CodeWarrior tniegraled Develop¬ 
ment Environ men I (IDE) has won every 
major award given lo Mac tlcvcloprncnL 
software. Its the worldwide standard for 





CWcWtiHmt lirrpji vuo ahviul of the tun'r wi/li 
and fuiutr OS X 


creating Mac software, and continues to 

lead rhe indusiry 

Check out these CodeWarrior benefits: 

fc^ Thc statc-of-Lhc-ari IDE sliorlens 
your drvefopmeuf time 

%/ Everything you need in one box... 
project manager, editor, compilers, 
debuggers, linkers, assemblers, 
profilers, a file compare utility our 
world-class framework PowcrPlant ' 
and the Ilexibilily to plugdn third 
party components. 

^ Use the furriiliar tfmlset 
to develop for all the major 
platforms, including Windows';; 
Linux, 5iobris7 game consoles 
and embedded platforms- 

✓ lightesi ISO/lbC C++ standards 
fompfitirifr 

✓ C, C++ and Java “ support 


fA 


iTwtrowerKs 


CodeWarrior 

for Mac OS 


Go with the warld-class standard. 

Use the same powerful, Ilexible, 
fast loolscl that built world-class 
apps like Adobe* Photoshop* and 
NeLscape* Navigator^ 

See for yourself. 

DoiVi just take our word for it. 

Gel your FREE* 30-day evaluation 
edition of CodeWarrior for Mac OS 
and pul it to the Lest. 



Discover why over 
I 200,000 programmers 
I worldwide use CodeWarrior. 

Call today or order online 
FREE 30-day evaluation 

WWW. metpowepks . com/go/mactecli 

1-800-377'5416 

^Non-relundabie shipping and hangiing of $1.95 
p^r CO applies, plus state saJes tax if applicable. 


Hurryt This ofler expires 4/30/20Q0. 
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